Skip to content

v0.1.0

Choose a tag to compare

@samuelduchesne samuelduchesne released this 13 Aug 21:44
· 34 commits to main since this release

This release adds a third package, @idfkit/weather, and fixes two httpSource
bugs that made @idfkit/schemas fail to load on common static hosts. It is also
the first release cut through the tagged release workflow rather than published by
hand, so all three packages now carry the same real version number.

The API is still not stable. This is a 0.x line.

Features

  • @idfkit/weather (#5), a new package for finding an EnergyPlus weather file
    and downloading it. StationIndex searches the climate.onebuilding.org TMYx
    index of 69,638 stations by name, WMO number, filename, or distance from a
    coordinate. fetchWeatherFiles and fetchEpw fetch a station's archive and
    return its EPW, DDY, and STAT files as text, ready to hand to
    @idfkit/engine.

    Search is synchronous and pure; retrieval is the only async part. Nothing outside
    the platform is required, because the ZIP reader is built on
    DecompressionStream, so the package runs unchanged in a browser, a worker, an
    edge runtime, or Node.

    import { loadBundledIndex } from '@idfkit/weather/node';
    import { fetchEpw } from '@idfkit/weather';
    
    const index = await loadBundledIndex();
    const [nearest] = index.nearest(41.98, -87.9, { maxDistanceKm: 50 });
    const epw = await fetchEpw(nearest.station);

    climate.onebuilding.org sends no CORS header, so calls from a page need a proxy.
    The rewriteUrl, baseUrl, and fetch options are there to route through one.

  • geocode and detectLocation (#5) turn a place name or the caller's IP
    address into the [latitude, longitude] pair you spread straight into
    StationIndex.nearest. They share one rate limiter that holds to the upstream geocoder's
    one-request-per-second policy, so you cannot accidentally get yourself blocked by
    looping over a list of cities.

  • @idfkit/weather/node (#5) reads the station index bundled with the package
    straight off disk with loadBundledIndex, and writes downloaded files out, so a
    script can search without touching the network at all. In the browser,
    loadStationIndex fetches the same index over HTTP.

Fixes

  • Schemas load from hosts that serve .gz with Content-Encoding: gzip (#4),
    including the Vite dev server, nginx with gzip_static on, and several static
    hosts. httpSource inflated every response unconditionally, so a body the HTTP
    client had already inflated failed with incorrect header check. In the browser
    that surfaced as a bare TypeError: Failed to fetch pointing nowhere near the
    cause. The payload is now checked for the gzip magic bytes and inflated only when
    it is actually compressed.

  • httpSource accepts a same-origin path such as httpSource('/schemas/'),
    the form the README documents (#3). It previously threw TypeError: Invalid URL
    before making any request, because the base was required to be absolute. Relative
    bases now resolve against the document base, the way fetch('/schemas/...')
    does. In Node, where there is no document base, a relative base is still an error,
    but it is raised when a schema is read rather than at construction, so building a
    SchemaBundle at module scope is safe in server-rendered apps.

Packaging

  • @idfkit/weather now carries a real version number. Its first upload to npm went
    out as 0.0.0, the in-repo placeholder that the release tooling treats as "not a
    release".
  • The release workflow publishes all three packages. It previously published only
    @idfkit/schemas and @idfkit/core, so a tagged release would have left weather
    behind.

Upgrade notes

  • @idfkit/core and @idfkit/schemas upgrade transparently from 0.0.1. Both
    fixes are internal to schema loading, and no API changed.
  • If you installed @idfkit/weather@0.0.0, upgrade to 0.1.0. The code is the
    same; the version is not.
  • The three packages are versioned and released together. Install them at matching
    versions: @idfkit/core depends on @idfkit/schemas at an exact version, so a
    mismatched pair will not resolve.
npm install @idfkit/core@0.1.0 @idfkit/schemas@0.1.0 @idfkit/weather@0.1.0