npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@idfkit/engine

v0.6.0

Published

Run building energy simulations in the browser or Node via WebAssembly. Framework-agnostic loader, worker and output parsers.

Readme

@idfkit/engine

Run building energy simulations in the browser, via WebAssembly. No server, no install, no upload — the model never leaves the page. The same engine also runs in Node, from @idfkit/engine/node.

This package is the loader, worker and output parsers. It carries no engine binary of its own; pair it with @idfkit/engine-assets, whose package version is the EnergyPlus version it bundles.

npm install @idfkit/engine @idfkit/[email protected]

Quickstart

Assets have to be reachable over HTTP at runtime. The reliable way is to copy them somewhere your app serves, and point the loader at that path:

// package.json
{
  "scripts": {
    "prebuild": "idfkit-engine-assets public/energyplus",
    "predev": "idfkit-engine-assets public/energyplus"
  }
}
import { createEnergyPlus } from '@idfkit/engine';

const ep = await createEnergyPlus({
  assetBaseUrl: '/energyplus',
  onConsole: (line) => console.log(line),
  onProgress: ({ phase, progress }) => console.log(phase, progress),
});

const result = await ep.run({ idf, epw });

if (result.success) {
  // `variables` is a Map keyed by the output file's variable id.
  console.log(`${result.eso?.variables.size ?? 0} output variables`);
} else {
  console.error(result.fatalError);
  for (const entry of result.err?.entries ?? []) console.error(entry.message);
}

ep.dispose();

Add public/energyplus/ to .gitignore — it is generated, and it is ~50 MB.

Running in Node

@idfkit/engine/node runs the same engine binary on a worker_threads worker. It returns the same engine, with the same run(), results, errors and lifecycle, so the same model and weather give the same numbers in a test, a script or a server as in the browser.

import { readFile } from 'node:fs/promises';
import { createEnergyPlus } from '@idfkit/engine/node';

const ep = await createEnergyPlus();
const result = await ep.run({
  idf: await readFile('model.idf', 'utf8'),
  epw: await readFile('weather.epw', 'utf8'),
});
ep.dispose();

Differences from the browser entry:

  • assetBaseUrl is optional. It defaults to the installed @idfkit/engine-assets, together with that package's wasmFile and loaderFile. Under Node that package knows where it is on disk; in a browser bundle it does not, which is why the browser entry has no default.
  • Locations take file paths. assetBaseUrl and workerUrl accept a filesystem path or a file: URL. https: asset URLs work too.
  • No copy step and no serving requirements. Nothing is served over HTTP.
  • Mid-run cancel() needs only the binary. Node always has a postable SharedArrayBuffer, so canCancelMidRun depends only on whether the binary has the cancellation hook.
  • The process can exit without dispose(). The worker keeps the process alive only while a load or a run is in flight.

If your Node app is bundled into a single file, import.meta.url no longer points at the installed packages. Pass assetBaseUrl and workerUrl explicitly in that case. When a default location does not exist, the loader says which one it looked for.

Choosing an EnergyPlus version

The asset package's version is the EnergyPlus version:

npm install @idfkit/[email protected]   # EnergyPlus version 26.2.0 software
npm install @idfkit/[email protected]   # EnergyPlus version 25.2.0 software

Rebuilds of the same upstream release use the PATCH slot: 26.1.1, 26.1.2. A prerelease suffix like 26.2.0-build.2 does not work here -- npm sorts a prerelease BELOW its release and excludes it from ordinary ranges, so @idfkit/[email protected] and ^26.2.0 would both skip it and users would never receive the rebuild. Reserve prereleases for builds nobody should adopt automatically.

To offer several versions at runtime, skip the copy step and point assetBaseUrl at a CDN per version:

const ep = await createEnergyPlus({
  assetBaseUrl: `https://cdn.jsdelivr.net/npm/@idfkit/engine-assets@${version}/assets`,
  // The binary is named after its version, so this must move with it. Each
  // asset package exports the right value as `wasmFile`.
  wasmFile: `energyplus.js-${version}.wasm`,
  // The worker ships in @idfkit/engine, a different package, so it cannot be
  // derived from assetBaseUrl here.
  workerUrl: 'https://cdn.jsdelivr.net/npm/@idfkit/engine/dist/engine.worker.js',
});

That path is cross-origin, which brings the caveats in the next section.

Serving requirements

| Requirement | Why | | --- | --- | | Content-Type: application/wasm on .wasm | Streaming compilation rejects other types | | Long-lived immutable caching | The binary is ~28 MB and content-addressed by version | | worker-src blob: in your CSP | Only if loading the worker cross-origin — see below | | script-src 'wasm-unsafe-eval' in your CSP | Compiling the WebAssembly. 'unsafe-eval' is not needed: under a policy without it, the glue scripts are loaded with importScripts() instead of new Function, so script-src must allow the asset origin. The exception is calling expandObjects() yourself on the page: outside the worker there is no importScripts(), so that use still needs 'unsafe-eval' |

Browser floor. Engine binaries built with WebAssembly exception handling — every asset package published after idfkit-engine#11 — need Chrome/Edge 95, Firefox 100, or Safari and iOS Safari 15.2. The engine uses exceptions to report its own fatal errors, so this is not optional on those builds. The loader itself has no such requirement, and an older asset package does not either.

Cross-origin loading. A worker script cannot itself be cross-origin, so when workerUrl is on another origin the loader wraps it in a same-origin Blob that importScripts() the real one. That needs worker-src blob: in your CSP, and the remote origin must send permissive CORS headers. Serving from your own origin avoids all of this, which is why the copy step is the documented default.

Threads and isolation. The bundled build is single-threaded and runs without cross-origin isolation (COOP/COEP). Those headers buy one thing here: cancel() being able to stop a run already under way, which needs a SharedArrayBuffer to reach the blocked worker. See engine.cancel(). If you swap in a threaded build you will need both headers regardless.

API

createEnergyPlus(options): Promise<EnergyPlusEngine>

Loads the runtime. Downloads and compiles ~28 MB, so call it once and reuse the result across runs.

| Option | Default | Notes | | --- | --- | --- | | assetBaseUrl | required | Where the WASM/IDD/datasets live. No default exists — this package ships no binary. | | workerUrl | ${assetBaseUrl}/engine.worker.js | The copy step puts it there. Override only if the worker is served elsewhere. | | wasmFile | energyplus.js-26.2.wasm | Must match your asset package version. | | loaderFile | energyplus.js | Emscripten glue filename. | | loadTimeoutMs | 30000 | Raise on slow connections. | | onConsole | — | Every stdout/stderr line. | | onProgress | — | Coarse phase + percentage. | | onDispose | — | Fires once the engine becomes unusable. error is set only for an unsolicited worker death, absent for your own dispose(). |

engine.run({ idf, epw?, files?, outputs? }): Promise<EngineRunResult>

Runs one simulation. HVACTemplate:* objects are expanded automatically first.

Resolves even when the engine fails. A model that does not converge is data, not an exception — check result.success and read result.err. A failed HVACTemplate expansion and a cancelled run also resolve. It rejects only when the run could not be attempted at all (worker died, runtime never loaded, engine disposed).

Returns exitCode, success, cancelled, err, eso, mtr, rdd, mdd, sql, html, csv, expand, omittedOutputs, consoleOutput, fatalError and crash.

crash is set only when a C++ exception unwound out of the engine instead of being handled inside it — { type, message }, e.g. EnergyPlus::FatalError. That is a defect in the engine binary, not in the model: report it with the asset package version rather than asking the user to fix their input.

Runs are serialised; a second run() while one is in flight is rejected.

eso and mtr hold each series as typed arrays: values is a Float64Array, and timestampAt(series, i) gives the timestamp of values[i] from a table all the series of one file share. That is 12 bytes a value, where an object per value cost ~140 and took an annual time-step run into gigabytes. The buffers are transferred out of the worker, not copied.

import { findVariables, getTimeSeries, timestampAt } from '@idfkit/engine';

const [temperature] = findVariables(result.eso!, 'Zone Mean Air Temperature');
const series = getTimeSeries(result.eso!, temperature!.id)!;
const peak = series.values.reduce((a, b) => Math.max(a, b), -Infinity);
// indexOf is -1 for an empty series, and timestampAt throws on an index it has no value for.
const at = series.values.indexOf(peak);
const when = at >= 0 ? timestampAt(series, at) : undefined; // { month, day, hour, ... }

Reading back less: outputs

Every output the model wrote is read back and, for eso and mtr, parsed. For an annual timestep model that is tens of megabytes copied out of the WASM heap, decoded and parsed — wasted on an app that reads its results from the SQLite output.

const result = await ep.run({ idf, epw, outputs: { eso: false, mtr: false } });
const db = await parseSQL(result.sql!);

Keys are eso, mtr, rdd, mdd, csv, html and sql; each defaults to true, and naming one does not switch off the others. Prefer this to making the model suppress the files with OutputControl:Files — that edits the user's document to save work in the parser.

eplusout.err is always read: success and fatalError come from it. Whatever you deselect is absent from the result and named in result.omittedOutputs, so "not read" stays distinguishable from "the model never wrote one".

Models that read a file: files

Schedule:File, Table:Lookup, Chiller:Electric:ASHRAE205 and friends name a file the engine has to be able to open. Pass its contents in files, keyed by exactly the path the model names:

// Schedule:File,
//   Occupancy, Fraction,
//   occupancy.csv,         !- File Name
//   1, 1, 8760, Comma, No, 60;

await ep.run({ idf, files: { 'occupancy.csv': csvText } });

Values may be a string or a Uint8Array — ASHRAE 205 representations are commonly CBOR and WINDOW data files are binary.

The rules, all of them:

  • Keys are relative to the model, and subdirectories work: a model naming data/profile.csv needs the key data/profile.csv.
  • Keys are case-sensitive, because the simulation filesystem is. Occupancy.CSV will not open occupancy.csv.
  • A leading /, a .., a backslash, or a name the engine owns (input.idf, weather.epw, Energy+.idd, anything under output/ or datasets/) is rejected — run() rejects, since that is a mistake in your code.
  • A model naming a file that is not in files fails before the engine starts, resolving with success: false and a fatalError naming the object, the field and the path. That is a modelling problem, so it resolves like any other failed run.
  • Staged files last exactly one run. The next run() on the same engine starts from a clean filesystem.

To find out what a model needs before running it — to prompt for an upload, say — use detectExternalFileReferences(idf), exported from the package root.

ExternalInterface:* FMU objects are not covered: they need a co-simulation partner process, not a file.

engine.cancel() / engine.dispose()

Whether cancel() can stop a run already under way is reported by engine.canCancelMidRun. Check it before labelling a "Stop" button.

When it is true, the engine checks for the cancellation between timesteps and between environments, breaks out of its own loops, and still writes and closes its output files. run() resolves with cancelled: true and the engine is immediately reusable, with no reload.

When it is false, callMain is synchronous inside the worker and blocks the thread the cancel message would be delivered on, so the cancellation only lands if it arrives before the engine starts. To stop such a run, call cancel() then dispose() and create a new engine. That costs a full ~28 MB reload, so reserve it for a user who explicitly wants out.

Either way cancellation resolves rather than rejecting. dispose() after a cancel() also resolves the in-flight run as cancelled: true, because the discard is then known to be the cancellation taking effect rather than a crash; dispose() with no preceding cancel() still rejects it.

canCancelMidRun needs two things and reports false if either is missing: a cross-origin isolated page (Cross-Origin-Opener-Policy: same-origin plus Cross-Origin-Embedder-Policy: require-corp), because the request reaches the blocked worker through a SharedArrayBuffer; and an engine binary built with the cancellation hook, which the loader asks the binary about directly, since an asset package's version names its EnergyPlus release and says nothing about build flags.

An engine can also die on its own -- a worker crash, not a dispose() you called. Check engine.isDisposed, or pass onDispose to createEnergyPlus(), to notice that instead of only discovering it when the next call rejects:

const ep = await createEnergyPlus({
  assetBaseUrl: '/energyplus',
  onDispose: (error) => {
    // error is set for an unsolicited death; undefined for your own dispose().
  },
});

Reading eplusout.sql

The SQLite output carries the tabular summary reports that have no ESO/MTR equivalent. It needs sql.js, an optional peer dependency:

npm install sql.js
import { parseSQL, configureSqlJs } from '@idfkit/engine/sql';

// Default fetches the sql.js runtime from sql.js.org. Override it if your CSP
// blocks that origin, or if you need to work offline.
configureSqlJs({ locateFile: (f) => `/sql-js/${f}` });

const db = await parseSQL(result.sql!);

EnergyPlus writes ReportData — the table holding every reported value — with no index on the variable it belongs to, so an unindexed getTimeSeries() scans the whole run. parseSQL therefore builds that index while loading. On a 40 MB annual file (1.8 M rows) that costs ~0.9 s once and takes five series from ~490 ms to ~130 ms; a database opened only for the tabular reports can skip it:

const db = await parseSQL(result.sql!, { indexTimeSeries: false });
renderSummary(db.getTabularData('AnnualBuildingUtilityPerformanceSummary'));
queueMicrotask(() => db.ensureTimeSeriesIndex()); // later, off the critical path

getTabularData(report, table?) pivots a report into { columns, units, rows, rowUnits }. columns are the bare names EnergyPlus wrote ('Total Energy', not 'Total Energy [GJ]'), after a leading 'Row'. rows has one entry per row EnergyPlus wrote, so a row name can repeat: across tables when table is omitted (both Utility Use tables have an HVAC row), across the per-zone or per-key copies of one table, and for separator rows.

EnergyPlus records units in a separate column, per cell: the column label's unit, or the row label's where the column has none ('Latitude [deg]' is stored as 'Latitude' with 'deg'). So units sits beside columns, index for index -- the one unit a column recorded, or null for 'Row', for a column with no unit, and for one that recorded more than one -- and rowUnits beside rows: the one unit a row recorded in the columns whose units entry is null. A cell's unit is units[c] ?? rowUnits[r]. It is never guessed, so a null means "show no unit", not "assume the usual one":

const t = db.getTabularData('AnnualBuildingUtilityPerformanceSummary', 'Site and Source Energy');
// t.columns -> ['Row', 'Total Energy', 'Energy Per Total Building Area', ...]
// t.units   -> [null,  'GJ',           'MJ/m2',                          ...]

const g = db.getTabularData('InputVerificationandResultsSummary', 'General');
// g.units    -> [null, null]   (one 'Value' column, its units on the rows)
// g.rowUnits -> [null, null, null, 'deg', 'deg', 'm', ...]

Meters and variables share one dictionary here: getVariables() returns both, isMeter tells them apart, and getTimeSeries(id) reads either. getEnvironments() gives each period's index (what timestampAt(series, i).environmentIndex refers to) and environmentType; its latitude/longitude are 0, because the SQLite output stores no site location — read those from result.eso?.environments.

A query naming a column the database does not have throws rather than answering empty. That can only be a defect in this package, and a silent empty result is indistinguishable from a model that reported nothing — which is how #14 survived a release. A table that is simply absent is still tolerated.

What is and is not supported

The browser build is not the full desktop engine. Verified against the shipped binary:

Not available

| Feature | Why | | --- | --- | | PythonPlugin:* / Python EMS API | Compiled with LINK_WITH_PYTHON=OFF. Use EMS/Erl instead — it is fully supported. | | ShadowCalculation → PixelCounting | The one GPU path in EnergyPlus (OpenGL via Penumbra). Compiled with OPENGL_REQUIRED=OFF. Degrades gracefully: warns and reverts to PolygonClipping. | | GHX borehole field design | Needs PYTHON_CLI. Modelling a pre-sized GHX is fine. | | EPMacro, IDFVersionUpdater | Separate Fortran binaries, not shipped. Pre-run natively. | | ExternalInterface:* (FMU / BCVTB) | Needs sockets and a co-simulation partner process. | | Multithreading | Single-threaded by design — which is why no COOP/COEP headers are needed. |

Available: HVACTemplate:* (via the bundled ExpandObjects), the Slab and Basement ground heat transfer preprocessors (GroundHeatTransfer:Slab:* and GroundHeatTransfer:Basement:*, run automatically by run(); they need an EPW and an asset package that ships slab.wasm and basement.wasm, which 25.2.1 and 26.1.1 onwards do), EMS/Erl, SQLite output, Foundation:Kiva, AirflowNetwork, conduction finite difference and PCM.

Memory ceiling: 1 GB (starts at 256 MB and grows). Large models — many zones, sub-hourly output, long run periods — can exhaust it. Request fewer output variables or shorten the run period before suspecting the model.

Full detail, including agent-facing guidance, is in .agents/skills/using-idfkit-engine/references/capability-support.md.

Validation

Every release is verified to reproduce the native EnergyPlus 26.2.0 build across annual simulations, on a corpus chosen to stress distinct physics:

| Case | Stresses | Data points | | --- | --- | --- | | envelope-freefloat | Conduction and infiltration, no HVAC to damp errors | 1,242,704 | | solar-fenestration | Solar position, transmission, angular dependence | 1,523,712 | | thermal-mass-pcm | Phase-change material via conduction finite difference | 387,552 | | hvac-airloop-plant | Air loop + plant, component sizing, controller iteration | 639,480 |

Each reported variable is reduced to a fingerprint — count, sum, min, max and an order-sensitive checksum — and compared against the native result. Aggregates (sum, checksum) must agree to 1e-9 relative; order statistics (min, max) to 1e-6, because a single controller iterating once more at one timestep relocates an extremum. Variable and data-point counts must match exactly.

The worst divergence measured across the corpus is 3.5e-9, on the maximum of one VAV outlet humidity ratio — whose own sum and checksum agree to better than 1e-9. Everything else is tighter.

Reproduce it yourself:

npm run differential:reference   # needs a native EnergyPlus install
npm run test:differential        # needs only a browser

On ASHRAE Standard 140 / BESTEST. This suite is not Standard 140. Those case files are copyrighted by ASHRAE and are redistributed by nobody — they are absent from both the EnergyPlus source tree and its installer — so this corpus uses EnergyPlus's own BSD-licensed test files instead.

The claim above is deliberately narrow and entirely about this package: the WebAssembly build is numerically indistinguishable from the native build. The Standard 140 validation of the simulation engine itself is NREL's, performed and published by them for EnergyPlus. What this test establishes is that compiling to WebAssembly does not disturb it.

Attribution

This package runs EnergyPlus version 26.2.0 software, compiled to WebAssembly. EnergyPlus is developed by NREL and the U.S. Department of Energy and is distributed under its own licence — see LICENSE-EnergyPlus.txt and NOTICE in @idfkit/engine-assets.

This project is not affiliated with, endorsed by, or sponsored by NREL, the U.S. Department of Energy, or any EnergyPlus copyright holder.

The loader, worker and parsers in this package are MIT licensed.