cppmodel 0.0.0-stage → 0.9.1

package/LICENSE

@@ -0,0 +1,9 @@
+CppModel
+Copyright (c) Control Edge AB. All rights reserved.
+
+This package and the CppModel library it contains are proprietary software of Control Edge AB.
+They are licensed, not sold, and may only be used under the CppModel Terms of Service:
+https://www.cppmodel.com/Tos.html
+
+The package also contains third-party components, each under its own license; see the licenses
+folder.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# CppModel for Node.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Write [CppModel](https://cppmodel.com) simulations in JavaScript or TypeScript. Every run fetches
+the inputs and parameters posted for it in your CppModel workspace and submits its execution there,
+just like a C or C++ simulation built with the CppModel SDK.
+
+```sh
+npm install cppmodel
+```
+
+Works on Linux (x64 and arm64, glibc 2.28+), Windows (x64 and ARM64) and macOS 11+ (Apple silicon
+and Intel) with Node.js 18 or later. The package contains the CppModel library for each of these
+platforms, so nothing needs compiling or installing.
+
+## A simulation
+
+```js
+import { Simulation } from 'cppmodel';
+
+class Heater extends Simulation {
+    init() {
+        this.temperature = 20.0;
+    }
+
+    step(timeMs) {
+        const setpoint = this.inputs.get('Setpoint', 22.0);        // input, with its fallback
+        const gain = this.parameters.get('HeaterGain', 0.05);      // parameter, with its fallback
+
+        const heaterOn = this.temperature < setpoint;              // the controller under test
+        this.temperature += heaterOn ? gain : -0.01;
+
+        this.outputs
+            .set('Temperature', this.temperature)
+            .set('HeaterOn', heaterOn)
+            .set('CppModel.Step', timeMs)
+            .set('CppModel.StepResult', this.temperature < setpoint + 1.0);
+    }
+}
+
+const simulation = new Heater('Example - Heater (Node)', 60_000, 100);
+process.exitCode = simulation.run();
+simulation.close();
+```
+
+`run()` fetches the pending inputs and parameters, calls `init()`, then `step(timeMs)` for every step
+from 0 to `totalTimeMs`, then `finalize()`, and submits the execution. It returns 0 when every step
+passed, otherwise the `CppModel.Step` of the first step whose `CppModel.StepResult` was 0.
+
+An exception thrown in `init()`, `step()` or `finalize()` aborts the run, submits nothing and is
+rethrown by `run()`.
+
+Instead of extending `Simulation`, you can pass the functions as options; they get the simulation as
+their first argument:
+
+```js
+const sim = new Simulation('Ramp', 1000, 100, {
+    step: (sim, timeMs) => sim.outputs.set('Ramp', timeMs),
+});
+sim.run();
+```
+
+`require('cppmodel')` works too, and TypeScript types are included.
+
+## Inputs, outputs and parameters
+
+| | |
+|---|---|
+| `sim.inputs.get(name, fallback = 0)` | The input's value at the current step, or `fallback` (recorded as its value) |
+| `sim.inputs.load([{label, x, y}, ...])` | Loads input series locally (x in ms) |
+| `sim.outputs.set(name, value)` | Sets an output; it holds until set again and is recorded every step. Values are numbers; booleans become 1/0 |
+| `sim.outputs.get(name)` | The output's current value |
+| `sim.parameters.get(name, fallback)` | The parameter, storing `fallback` when it isn't set; a fetched value replaces the fallback |
+| `sim.parameters.set(name, value)` | Sets a parameter that fetched values never replace |
+| `sim.parameters.toObject()` | Every parameter |
+| `sim.results()` | The execution as submitted: `{inputs, results, parameters, ...}` |
+
+Inputs and outputs are numbers. Parameters keep their JSON type. All three have `has(name)`,
+`keys()` and `size`.
+
+## Things to know
+
+- **`run()` is synchronous.** It blocks the event loop until the simulation has finished, which is
+  fine for scripts and tests. In a server, run simulations in a
+  [worker thread](https://nodejs.org/api/worker_threads.html).
+- **Workspace access:** every run reads its inputs from and records its execution in your
+  workspace. Set `CPPMODEL_USERNAME` and `CPPMODEL_PASSWORD` for scripts and CI. Without
+  credentials, the first run prints a sign-in link and waits 60 seconds for you to sign in
+  (`CPPMODEL_LOGIN_TIMEOUT` changes that, in seconds); without a sign-in, `run()` throws.
+- **Fingerprint:** each execution records a `CppModel.BinaryFingerprint` of the simulation's code,
+  so the workspace can tell runs of the same code from runs of changed code. It is the fingerprint
+  of the file that creates the simulation. Set `sim.fingerprintFile` to use another file.
+- **Cleanup:** call `close()` when you're done with a simulation. One that is garbage-collected
+  is freed too.
+- **Errors:** a failing library call throws a `CppModelError` whose `status` is one of `Status`.
+
+## License
+
+The CppModel library is proprietary software of Control Edge AB, used under the
+[CppModel Terms of Service](https://www.cppmodel.com/Tos.html); see `LICENSE`. The package also
+contains third-party components under their own licenses, in `licenses/`.

package/examples/heater.mjs

@@ -0,0 +1,29 @@
+// A first-order heater: the controller under test switches it on below the setpoint.
+//
+// The same simulation as examples/minimal/simulation.cpp, in JavaScript. Run it with
+// CPPMODEL_USERNAME and CPPMODEL_PASSWORD set to submit the execution to your workspace.
+import { Simulation } from 'cppmodel';
+
+class Heater extends Simulation {
+    init() {
+        this.temperature = 20.0;
+    }
+
+    step(timeMs) {
+        const setpoint = this.inputs.get('Setpoint', 22.0);
+        const gain = this.parameters.get('HeaterGain', 0.05);
+
+        const heaterOn = this.temperature < setpoint; // the controller under test
+        this.temperature += (heaterOn ? gain : -0.01) * (this.stepMs / 100.0);
+
+        this.outputs
+            .set('Temperature', this.temperature)
+            .set('HeaterOn', heaterOn)
+            .set('CppModel.Step', timeMs)
+            .set('CppModel.StepResult', this.temperature < setpoint + 1.0);
+    }
+}
+
+const simulation = new Heater('Example - Heater (Node)', 60_000, 100);
+process.exitCode = simulation.run();
+simulation.close();

package/index.d.ts

@@ -0,0 +1,125 @@
+/** The major C API version this package is written against. */
+export declare const API_VERSION: 1;
+
+/** cm_status codes of the C API. */
+export declare const Status: {
+    readonly OK: 0;
+    readonly INVALID_ARGUMENT: 1;
+    readonly NOT_FOUND: 2;
+    readonly TYPE_MISMATCH: 3;
+    readonly INVALID_JSON: 4;
+    readonly CALLBACK: 5;
+    readonly INTERNAL: 6;
+};
+
+/** A CppModel library call failed. */
+export declare class CppModelError extends Error {
+    readonly status: number;
+}
+
+/** A JSON value, as parameters hold them. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+
+/** A time series: x in milliseconds. */
+export interface Series {
+    label: string;
+    x: number[];
+    y: number[];
+}
+
+/** The execution as it is (or would be) submitted. */
+export interface Results {
+    inputs: Series[];
+    results: Series[];
+    parameters: { [name: string]: JsonValue };
+    executionTime: string;
+}
+
+export declare class Inputs {
+    /** The input's value at the current step, or `fallback` (then recorded as its value) when nothing was loaded for it. */
+    get(name: string, fallback?: number): number;
+    /** Loads series locally. */
+    load(series: Series[]): void;
+    has(name: string): boolean;
+    /** The inputs read or loaded so far, in name order. */
+    keys(): string[];
+    readonly size: number;
+}
+
+export declare class Outputs {
+    /** Sets an output; it holds until set again and is recorded every step. Booleans are stored as 1 and 0. */
+    set(name: string, value: number | boolean): this;
+    /** The output's current value; reading an output that was never set creates it with 0. */
+    get(name: string): number;
+    has(name: string): boolean;
+    keys(): string[];
+    readonly size: number;
+}
+
+export declare class Parameters {
+    /** The parameter's value, storing `fallback` first when it isn't set. A fetched value replaces a stored fallback. */
+    get<T extends JsonValue>(name: string, fallback: T): T extends number ? number : T extends string ? string : T extends boolean ? boolean : JsonValue;
+    /** Sets a parameter that fetched values never replace. */
+    set(name: string, value: JsonValue): this;
+    has(name: string): boolean;
+    keys(): string[];
+    readonly size: number;
+    /** Every parameter as a plain object. */
+    toObject(): { [name: string]: JsonValue };
+}
+
+export interface SimulationOptions<S extends Simulation = Simulation> {
+    /** When true, run() doesn't reach the workspace and then throws: a run that skips the workspace verifies nothing. */
+    offline?: boolean;
+    init?: (simulation: S) => void;
+    step?: (simulation: S, timeMs: number) => void;
+    finalize?: (simulation: S) => void;
+}
+
+/**
+ * A CppModel simulation. Extend it and override init(), step(timeMs) and finalize(), or pass them
+ * as options. run() is synchronous.
+ */
+export declare class Simulation {
+    constructor(name: string, totalTimeMs: number, stepMs: number, options?: SimulationOptions);
+
+    readonly inputs: Inputs;
+    readonly outputs: Outputs;
+    readonly parameters: Parameters;
+
+    /** Called once before the first step. */
+    init(): void;
+    /** Called every step with the simulation time in milliseconds. */
+    step(timeMs: number): void;
+    /** Called once after the last step. */
+    finalize(): void;
+
+    /** Runs the simulation: 0 when every step passed, otherwise the CppModel.Step of the first failing step (or -1). */
+    run(): number;
+    /** Deletes the simulation on the server (same as deleting it in the UI). Call before run(). */
+    resetData(): void;
+    /** The execution as it is (or would be) submitted. */
+    results(): Results;
+    /** Applies a GET /simulations/{id}/inputs response. Values already set are kept. */
+    applyInputs(response: { inputs?: Series[]; parameters?: { [name: string]: JsonValue } }): void;
+
+    name: string;
+    totalTimeMs: number;
+    stepMs: number;
+    offline: boolean;
+    /**
+     * The file whose fingerprint is recorded as CppModel.BinaryFingerprint. Defaults to the file that
+     * created the simulation; null means the Node.js executable's fingerprint.
+     */
+    fingerprintFile: string | null;
+    result: number;
+    readonly passed: boolean;
+
+    /** Frees the simulation. It is also freed when garbage-collected. */
+    close(): void;
+}
+
+/** The shared library this package loads. */
+export declare function libraryPath(): string;
+/** The release version of the loaded CppModel library, e.g. "0.8.0". */
+export declare function libraryVersion(): string;

package/index.js

@@ -0,0 +1,475 @@
+'use strict';
+// CppModel for Node.js: a JavaScript wrapper over the CppModel C API (include/cppmodel.h), loaded
+// with koffi. Persistent simulations are C/C++ only.
+const path = require('node:path');
+const { fileURLToPath } = require('node:url');
+const koffi = require('koffi');
+
+// The major C API version this wrapper is written against; the library must report the same.
+const API_VERSION = 1;
+
+const Status = Object.freeze({
+    OK: 0,
+    INVALID_ARGUMENT: 1,
+    NOT_FOUND: 2,
+    TYPE_MISMATCH: 3,
+    INVALID_JSON: 4,
+    CALLBACK: 5,
+    INTERNAL: 6,
+});
+
+const LIBRARY_NAMES = { win32: 'cppmodel.dll', darwin: 'libcppmodel.dylib' };
+
+/** The shared library to load: $CPPMODEL_LIBRARY, else the one bundled for this platform. */
+function libraryPath() {
+    if (process.env.CPPMODEL_LIBRARY) return process.env.CPPMODEL_LIBRARY;
+    // One universal library serves both macOS architectures.
+    const platform = process.platform === 'darwin' ? 'darwin' : `${process.platform}-${process.arch}`;
+    return path.join(__dirname, 'prebuilds', platform, LIBRARY_NAMES[process.platform] || 'libcppmodel.so.1');
+}
+
+function load() {
+    const file = libraryPath();
+    let library;
+    try {
+        library = koffi.load(file);
+    } catch (error) {
+        throw new Error(`cppmodel: cannot load the CppModel library ${file} (${error.message}). ` +
+            `Reinstall the cppmodel package on a supported platform, or set CPPMODEL_LIBRARY.`);
+    }
+    // Only the functions the wrapper uses; cm_require_non_interactive is left out because it exits the process.
+    koffi.proto('int cm_callback(void *simulation, uint64_t time_ms, void *user_data)');
+    const f = (definition) => library.func(definition);
+    const c = {
+        apiVersion: f('int cm_api_version(void)'),
+        version: f('const char *cm_version(void)'),
+        lastErrorMessage: f('const char *cm_last_error_message(void)'),
+        create: f('int cm_simulation_create(const char *name, uint64_t total_time_ms, uint64_t step_ms, _Out_ void **out)'),
+        destroy: f('int cm_simulation_destroy(void *simulation)'),
+        setName: f('int cm_simulation_set_name(void *simulation, const char *name)'),
+        getName: f('int cm_simulation_get_name(void *simulation, _Out_ const char **out)'),
+        setTiming: f('int cm_simulation_set_timing(void *simulation, uint64_t total_time_ms, uint64_t step_ms)'),
+        getTiming: f('int cm_simulation_get_timing(void *simulation, _Out_ uint64_t *total_time_ms, _Out_ uint64_t *step_ms)'),
+        setRunOffline: f('int cm_simulation_set_run_offline(void *simulation, int offline)'),
+        setFingerprintFile: f('int cm_simulation_set_fingerprint_file(void *simulation, const char *path)'),
+        setInitCallback: f('int cm_simulation_set_init_callback(void *simulation, cm_callback *callback, void *user_data)'),
+        setStepCallback: f('int cm_simulation_set_step_callback(void *simulation, cm_callback *callback, void *user_data)'),
+        setFinalizeCallback: f('int cm_simulation_set_finalize_callback(void *simulation, cm_callback *callback, void *user_data)'),
+        run: f('int cm_simulation_run(void *simulation)'),
+        resetData: f('int cm_simulation_reset_data(void *simulation)'),
+        getResult: f('int cm_simulation_get_result(void *simulation, _Out_ int *out)'),
+        setResult: f('int cm_simulation_set_result(void *simulation, int result)'),
+        resultsJson: f('int cm_simulation_results_json(void *simulation, _Out_ const char **out)'),
+        applyInputsJson: f('int cm_simulation_apply_inputs_json(void *simulation, const char *json)'),
+        inputs: f('int cm_simulation_inputs(void *simulation, _Out_ void **out)'),
+        outputs: f('int cm_simulation_outputs(void *simulation, _Out_ void **out)'),
+        inputGet: f('int cm_input_get(void *inputs, const char *name, double fallback, _Out_ double *out)'),
+        inputsLoadJson: f('int cm_inputs_load_json(void *inputs, const char *series_json)'),
+        inputsContains: f('int cm_inputs_contains(void *inputs, const char *name, _Out_ int *out)'),
+        inputsCount: f('int cm_inputs_count(void *inputs, _Out_ size_t *out)'),
+        inputsKeyAt: f('int cm_inputs_key_at(void *inputs, size_t index, _Out_ const char **out)'),
+        outputSet: f('int cm_output_set(void *outputs, const char *name, double value)'),
+        outputGet: f('int cm_output_get(void *outputs, const char *name, _Out_ double *out)'),
+        outputsContains: f('int cm_outputs_contains(void *outputs, const char *name, _Out_ int *out)'),
+        outputsCount: f('int cm_outputs_count(void *outputs, _Out_ size_t *out)'),
+        outputsKeyAt: f('int cm_outputs_key_at(void *outputs, size_t index, _Out_ const char **out)'),
+        paramSetDouble: f('int cm_param_set_double(void *simulation, const char *name, double value)'),
+        paramSetJson: f('int cm_param_set_json(void *simulation, const char *name, const char *json)'),
+        paramGetJson: f('int cm_param_get_json(void *simulation, const char *name, _Out_ const char **out)'),
+        paramGetOrJson: f('int cm_param_get_or_json(void *simulation, const char *name, const char *fallback_json, _Out_ const char **out)'),
+        paramContains: f('int cm_param_contains(void *simulation, const char *name, _Out_ int *out)'),
+        paramCount: f('int cm_param_count(void *simulation, _Out_ size_t *out)'),
+        paramKeyAt: f('int cm_param_key_at(void *simulation, size_t index, _Out_ const char **out)'),
+    };
+    if (c.apiVersion() !== API_VERSION) {
+        throw new Error(`cppmodel: ${file} implements C API version ${c.apiVersion()}, this package needs version ${API_VERSION}`);
+    }
+    return c;
+}
+
+const c = load();
+const callbackPointer = koffi.pointer('cm_callback');
+
+/** A CppModel library call failed. `status` is one of the Status codes. */
+class CppModelError extends Error {
+    constructor(status, message) {
+        super(message);
+        this.name = 'CppModelError';
+        this.status = status;
+    }
+}
+
+function check(status) {
+    if (status !== Status.OK) throw new CppModelError(status, c.lastErrorMessage());
+}
+
+// Calls a C function whose last argument is an out pointer and returns what it wrote.
+function read(fn, ...args) {
+    const out = [null];
+    check(fn(...args, out));
+    return out[0];
+}
+
+function keys(count, keyAt, handle) {
+    const result = [];
+    const n = read(count, handle);
+    for (let index = 0; index < n; index++) result.push(read(keyAt, handle, index));
+    return result;
+}
+
+/** The simulation's inputs: time series whose value is read at the current step. */
+class Inputs {
+    #simulation;
+    #handle;
+
+    constructor(simulation, handle) {
+        this.#simulation = simulation;
+        this.#handle = handle;
+    }
+
+    #live() {
+        this.#simulation._live();
+        return this.#handle;
+    }
+
+    /** The input's value at the current step, or `fallback` (then recorded as its value) when nothing was loaded for it. */
+    get(name, fallback = 0) {
+        return read(c.inputGet, this.#live(), name, Number(fallback));
+    }
+
+    /** Loads series [{label: name, x: [ms, ...], y: [value, ...]}, ...]. */
+    load(series) {
+        check(c.inputsLoadJson(this.#live(), JSON.stringify(series)));
+    }
+
+    has(name) {
+        return read(c.inputsContains, this.#live(), name) !== 0;
+    }
+
+    /** The inputs read or loaded so far, in name order. */
+    keys() {
+        return keys(c.inputsCount, c.inputsKeyAt, this.#live());
+    }
+
+    get size() {
+        return read(c.inputsCount, this.#live());
+    }
+}
+
+/** The simulation's outputs. An output holds its value until set again and is recorded at the end of every step. */
+class Outputs {
+    #simulation;
+    #handle;
+
+    constructor(simulation, handle) {
+        this.#simulation = simulation;
+        this.#handle = handle;
+    }
+
+    #live() {
+        this.#simulation._live();
+        return this.#handle;
+    }
+
+    /** Sets an output. Values are numbers; booleans are stored as 1 and 0. */
+    set(name, value) {
+        check(c.outputSet(this.#live(), name, Number(value)));
+        return this;
+    }
+
+    /** The output's current value; reading an output that was never set creates it with 0. */
+    get(name) {
+        return read(c.outputGet, this.#live(), name);
+    }
+
+    has(name) {
+        return read(c.outputsContains, this.#live(), name) !== 0;
+    }
+
+    keys() {
+        return keys(c.outputsCount, c.outputsKeyAt, this.#live());
+    }
+
+    get size() {
+        return read(c.outputsCount, this.#live());
+    }
+}
+
+/** The simulation's parameters. They keep their JSON type: numbers, booleans, strings, arrays, objects or null. */
+class Parameters {
+    #simulation;
+
+    constructor(simulation) {
+        this.#simulation = simulation;
+    }
+
+    /**
+     * The parameter's value, storing `fallback` first when it isn't set. A fetched value replaces a
+     * stored fallback; a value set with set() is never replaced.
+     */
+    get(name, fallback) {
+        if (fallback === undefined) throw new TypeError(`parameters.get("${name}"): a fallback is required`);
+        return JSON.parse(read(c.paramGetOrJson, this.#simulation._live(), name, JSON.stringify(fallback)));
+    }
+
+    /** Sets a parameter that fetched values never replace. */
+    set(name, value) {
+        const handle = this.#simulation._live();
+        if (typeof value === 'number' && !Number.isInteger(value)) check(c.paramSetDouble(handle, name, value));
+        else check(c.paramSetJson(handle, name, JSON.stringify(value)));
+        return this;
+    }
+
+    has(name) {
+        return read(c.paramContains, this.#simulation._live(), name) !== 0;
+    }
+
+    keys() {
+        return keys(c.paramCount, c.paramKeyAt, this.#simulation._live());
+    }
+
+    get size() {
+        return read(c.paramCount, this.#simulation._live());
+    }
+
+    /** Every parameter as a plain object. */
+    toObject() {
+        const handle = this.#simulation._live();
+        const result = {};
+        for (const name of this.keys()) result[name] = JSON.parse(read(c.paramGetJson, handle, name));
+        return result;
+    }
+}
+
+// The file that created a simulation: the first call site outside this package, else the main script.
+function callerFile() {
+    const prepare = Error.prepareStackTrace;
+    try {
+        Error.prepareStackTrace = (_error, stack) => stack;
+        for (const site of new Error().stack) {
+            const file = site.getFileName();
+            if (!file || file === __filename || file.startsWith('node:')) continue;
+            return file.startsWith('file:') ? fileURLToPath(file) : file;
+        }
+    } finally {
+        Error.prepareStackTrace = prepare;
+    }
+    return process.argv[1];
+}
+
+// Frees simulations that were garbage-collected without close().
+const finalizer = new FinalizationRegistry((handle) => c.destroy(handle));
+
+/**
+ * A CppModel simulation.
+ *
+ * Either extend it and override init(), step(timeMs) and finalize(), or pass those as options
+ * taking the simulation as their first argument.
+ *
+ * run() fetches the pending inputs and parameters from the workspace, calls init(), then step()
+ * for every step from 0 to totalTimeMs, then finalize(), and submits the execution. An exception
+ * thrown in init(), step() or finalize() aborts the run (nothing is submitted) and is rethrown by
+ * run(). run() is synchronous: it blocks the event loop until the simulation has finished.
+ */
+class Simulation {
+    #handle;
+    #offline = false;
+    #fingerprintFile = null;
+    #functions;
+
+    constructor(name, totalTimeMs, stepMs, { offline = false, init, step, finalize } = {}) {
+        this.#handle = read(c.create, name, totalTimeMs, stepMs);
+        finalizer.register(this, this.#handle, this);
+        this.#functions = { init, step, finalize };
+        this.offline = offline;
+        const caller = callerFile();
+        const file = caller ? path.resolve(caller) : null;
+        if (file && c.setFingerprintFile(this.#handle, file) === Status.OK) this.#fingerprintFile = file;
+        this.inputs = new Inputs(this, read(c.inputs, this.#handle));
+        this.outputs = new Outputs(this, read(c.outputs, this.#handle));
+        this.parameters = new Parameters(this);
+    }
+
+    // ── Overridables ─────────────────────────────────────────────────────
+
+    /** Called once before the first step. */
+    init() {
+        if (this.#functions.init) this.#functions.init(this);
+    }
+
+    /** Called every step with the simulation time in milliseconds. */
+    step(timeMs) {
+        if (this.#functions.step) this.#functions.step(this, timeMs);
+    }
+
+    /** Called once after the last step. */
+    finalize() {
+        if (this.#functions.finalize) this.#functions.finalize(this);
+    }
+
+    // ── Running ──────────────────────────────────────────────────────────
+
+    /**
+     * Runs the simulation and returns its result: 0 when every step passed, otherwise the
+     * CppModel.Step of the first failing step (or -1).
+     */
+    run() {
+        const handle = this._live();
+        let failure = null;
+        // A callback that throws must return an error status itself: koffi would otherwise let the
+        // C run continue (and submit) and only rethrow at the end.
+        const register = (method) => koffi.register((_simulation, timeMs) => {
+            try {
+                method(Number(timeMs));
+                return Status.OK;
+            } catch (error) {
+                failure = { error };
+                return Status.CALLBACK;
+            }
+        }, callbackPointer);
+        // Registered only while running, so the simulation holds no callbacks that keep it alive.
+        const callbacks = [register(() => this.init()), register((t) => this.step(t)), register(() => this.finalize())];
+        try {
+            check(c.setInitCallback(handle, callbacks[0], null));
+            check(c.setStepCallback(handle, callbacks[1], null));
+            check(c.setFinalizeCallback(handle, callbacks[2], null));
+            const status = c.run(handle);
+            if (failure) throw failure.error;
+            check(status);
+            return this.result;
+        } finally {
+            c.setInitCallback(handle, null, null);
+            c.setStepCallback(handle, null, null);
+            c.setFinalizeCallback(handle, null, null);
+            callbacks.forEach((callback) => koffi.unregister(callback));
+        }
+    }
+
+    /** Deletes the simulation on the server (same as deleting it in the UI). Call before run(). */
+    resetData() {
+        check(c.resetData(this._live()));
+    }
+
+    /** The execution as it is (or would be) submitted: {inputs, results, parameters, ...}. */
+    results() {
+        return JSON.parse(read(c.resultsJson, this._live()));
+    }
+
+    /** Applies a GET /simulations/{id}/inputs response ({inputs: [...], parameters: {...}}). Values already set are kept. */
+    applyInputs(response) {
+        check(c.applyInputsJson(this._live(), JSON.stringify(response)));
+    }
+
+    // ── Properties ───────────────────────────────────────────────────────
+
+    get name() {
+        return read(c.getName, this._live());
+    }
+
+    set name(value) {
+        check(c.setName(this._live(), value));
+    }
+
+    #timing() {
+        const total = [0];
+        const step = [0];
+        check(c.getTiming(this._live(), total, step));
+        return [total[0], step[0]];
+    }
+
+    get totalTimeMs() {
+        return this.#timing()[0];
+    }
+
+    set totalTimeMs(value) {
+        check(c.setTiming(this._live(), value, this.stepMs));
+    }
+
+    get stepMs() {
+        return this.#timing()[1];
+    }
+
+    set stepMs(value) {
+        check(c.setTiming(this._live(), this.totalTimeMs, value));
+    }
+
+    /**
+     * When true, run() doesn't reach the workspace: nothing is fetched or submitted, and run() then
+     * throws, because a run that skips the workspace verifies nothing.
+     */
+    get offline() {
+        return this.#offline;
+    }
+
+    set offline(value) {
+        check(c.setRunOffline(this._live(), value ? 1 : 0));
+        this.#offline = Boolean(value);
+    }
+
+    /**
+     * The file whose fingerprint is recorded as CppModel.BinaryFingerprint, so that runs of the same
+     * code can be told apart from runs of changed code. Defaults to the file that created the
+     * simulation; null means the Node.js executable's fingerprint.
+     */
+    get fingerprintFile() {
+        return this.#fingerprintFile;
+    }
+
+    set fingerprintFile(file) {
+        const resolved = file === null || file === undefined ? null : path.resolve(file);
+        check(c.setFingerprintFile(this._live(), resolved));
+        this.#fingerprintFile = resolved;
+    }
+
+    /** 0 when every step passed; otherwise the CppModel.Step of the first failing step (or -1). */
+    get result() {
+        return read(c.getResult, this._live());
+    }
+
+    set result(value) {
+        check(c.setResult(this._live(), value));
+    }
+
+    get passed() {
+        return this.result === 0;
+    }
+
+    // ── Lifetime ─────────────────────────────────────────────────────────
+
+    /** @internal */
+    _live() {
+        if (this.#handle === null) throw new Error('the simulation is closed');
+        return this.#handle;
+    }
+
+    /** Frees the simulation. It is also freed when garbage-collected. */
+    close() {
+        if (this.#handle === null) return;
+        finalizer.unregister(this);
+        c.destroy(this.#handle);
+        this.#handle = null;
+    }
+}
+
+if (typeof Symbol.dispose === 'symbol') {
+    Simulation.prototype[Symbol.dispose] = function dispose() {
+        this.close();
+    };
+}
+
+/** The release version of the loaded CppModel library, e.g. "0.8.0". */
+function libraryVersion() {
+    return c.version();
+}
+
+module.exports = {
+    API_VERSION,
+    CppModelError,
+    Inputs,
+    Outputs,
+    Parameters,
+    Simulation,
+    Status,
+    libraryPath,
+    libraryVersion,
+};

package/licenses/IXWebSocket-LICENSE.txt

@@ -0,0 +1,29 @@
+Copyright (c) 2018 Machine Zone, Inc. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the
+   distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived
+   from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/licenses/cpp-httplib-LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 yhirose
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/licenses/jwt-cpp-LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Dominik Thalhammer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/licenses/nlohmann-json-LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License 
+
+Copyright (c) 2013-2025 Niels Lohmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/licenses/openssl-LICENSE.txt

@@ -0,0 +1,16 @@
+Apache License
+Version 2.0, January 2004
+
+Copyright (c) OpenSSL Project Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/licenses/picojson-LICENSE.txt

@@ -0,0 +1,25 @@
+Copyright 2009-2010 Cybozu Labs, Inc.
+Copyright 2011-2014 Kazuho Oku
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "cppmodel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.1",
+  "description": "Write CppModel simulations in Node.js",
+  "keywords": ["cppmodel", "simulation", "plant model", "testing", "embedded"],
+  "homepage": "https://cppmodel.com",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Control Edge AB <support@cedge.se>",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "examples/",
+    "prebuilds/",
+    "LICENSE",
+    "licenses/"
+  ],
+  "os": ["linux", "win32", "darwin"],
+  "cpu": ["x64", "arm64"],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "koffi": "3.3.2"
+  },
+  "scripts": {
+    "test": "node --test test/simulation.test.js"
+  }
+}