h5wasm

HDF5 Compound Datatypes (H5T_COMPOUND) can be written by passing a JavaScript Map representing a Structure of Arrays (SoA). The keys of the Map become the member names, and the values are arrays/TypedArrays representing the columns. h5wasm automatically interleaves them into the expected Array of Structures (AoS) format.

Automatic Inference: If dtype is omitted, types are guessed from the provided TypedArrays.

Explicit Schema: Pass an array of [name, type_string] tuples to dtype to enforce a specific layout.

Nested Compounds: Nest Map objects within each other to create deeply nested structures.

// 1. Create SoA using a Map
const particle_data = new Map([
  ['id', new Int32Array([10, 20, 30])],
  ['velocity', new Float64Array([1.1, 2.2, 3.3])]
]);

// 2. Write it
let new_file = new h5wasm.File("myfile.h5", "w");
new_file.create_dataset({ name: "particles", data: particle_data });

// 3. Reading it back returns an Array of Structures (AoS) format
const read_back = new_file.get("particles").value;
// Result: [[10, 1.1], [20, 2.2], [30, 3.3]]

// Nested Example
const nested_data = new Map([
  ['id', new Uint8Array([1, 2])],
  ['position', new Map([
    ['x', new Float64Array([10.1, 20.1])],
    ['y', new Float64Array([1.1, 2.2])]
  ])]
]);
new_file.create_dataset({ name: "nested", data: nested_data });

To use h5wasm directly in a browser without a build step, import the ESM module from a CDN. Because the WebAssembly module loads asynchronously, you must await h5wasm.ready to access the Module and its FS (FileSystem) object.

To work with files, you first write the file data into the Emscripten filesystem using FS.writeFile, then open it using the h5wasm.File constructor with an appropriate access mode (e.g., 'r' for reading).

import h5wasm from "https://cdn.jsdelivr.net/npm/h5wasm@latest/dist/esm/hdf5_hl.js";

// Wait for WASM to load
const Module = await h5wasm.ready;
const { FS } = Module;

// Load a file into the virtual filesystem
let response = await fetch("https://ncnr.nist.gov/pub/ncnrdata/vsans/202003/24845/data/sans59510.nxs.ngv");
let ab = await response.arrayBuffer();
FS.writeFile("sans59510.nxs.ngv", new Uint8Array(ab));

// Open the file for reading
let f = new h5wasm.File("sans59510.nxs.ngv", "r");

For browser-based applications, h5wasm provides optional helpers to handle file I/O via standard HTML elements.

• uploader: An event handler for <input type="file">. When triggered, it saves the uploaded file to the Emscripten virtual filesystem (Module.FS) using its original filename.
• download(file): Takes an h5wasm.File instance and triggers a browser download of a snapshot of that file.
• UPLOADED_FILES: An array containing references to files recently uploaded via the uploader.

Note: These helpers are available via the file_handlers.js ESM module.

import {uploader, download, UPLOADED_FILES} from "https://cdn.jsdelivr.net/npm/h5wasm@latest/dist/esm/file_handlers.js";

// 1. Setup Upload
document.getElementById("upload_selector").onchange = uploader;

// 2. Access uploaded file
const lastFile = UPLOADED_FILES[UPLOADED_FILES.length - 1];
let f = new h5wasm.File(lastFile, "r");

// 3. Download a file
let new_file = new h5wasm.File("myfile.h5", "w");
// ... perform writes ...
download(new_file);

SWMR allows one process to write to a file while multiple others read from it simultaneously.

Requirements:

1. The file must be created with at least libver: "v110".
2. The dataset must be chunked and extensible (maxshape must include null).

Workflow:

1. Open file in "w" mode with { libver: "v110" }.
2. Create a chunked dataset with maxshape: [null].
3. Call file.start_swmr_write().
4. Readers open the file using mode "Sr".
5. When the reader needs to see new data/shapes, call dataset.refresh().

Note: To append to a closed file, re-open with mode "Sa" or open with "a" and call start_swmr_write().

// Writer setup
const f_write = new h5wasm.File(FILEPATH, "w", { libver: "v110" });
const dset_write = f_write.create_dataset({
  name: "data",
  data: INITIAL_DATA,
  maxshape: [null], // Required for extensibility
  chunks: [10]
});

f_write.start_swmr_write();

// ... later extend and write
dset_write.resize([6]);
dset_write.write_slice([[3, 6]], new Float32Array([4, 5, 6]));
f_write.flush();

// Reader setup
const f_read = new h5wasm.File(FILEPATH, "Sr");
const dset_read = f_read.get("data");

dset_read.refresh(); // Refresh to see new shape/data
console.log(dset_read.value);