# clawhdf5-wasm

clawhdf5's HDF5 and NetCDF-4 reader compiled to WebAssembly with
wasm-bindgen, for the browser (and Node). Read-only. Two ways in:

- `open(bytes)` — a file already in memory (a dropped file, a fetched
  blob);
- `openUrl(url, opts)` — a file on a web server, read by HTTP range
  requests as each call needs its bytes, without downloading it
  (range-read milestone M4, [`docs/design/range-reads.md`](../../docs/design/range-reads.md)).

Both give `list`, `info`, `attrs`, `read` and `readHyperslab`; the remote
file's methods return promises, and `stats()` counts requests and bytes.
The JavaScript API, options, limits, package size and tests are documented
with the demo page, [`examples/wasm-viewer/README.md`](../../examples/wasm-viewer/README.md).

## Layout

- `src/core.rs` — the reader over any `clawhdf5_format::storage::Storage`
  (`Reader::open_storage`), plain Rust and tested natively.
- `src/lazy.rs` — the restartable "NeedBytes" cache behind `openUrl`: a
  call runs as a pass over the blocks fetched so far; a pass that misses is
  abandoned, the missing (and hinted) blocks are fetched, and the pass is
  run again. No block is evicted while a call runs.
- `js/remote.js` — the HTTP side: `fetch` with `Range`, checking every
  answer (a `206` with exactly the bytes asked for, same ETag/Last-Modified
  and length) so a call fails rather than return another file's bytes.
- `src/lib.rs` — the wasm-bindgen exports.

## Build and test

```bash
rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.129   # must equal the crate's wasm-bindgen
bash examples/wasm-viewer/build.sh                  # -> examples/wasm-viewer/pkg/
cargo test -p clawhdf5-wasm                         # native: h5py_interop, lazy, vl_strings
bash examples/wasm-viewer/test/run.sh               # Node + headless Chromium (not in CI)
```

`CLAWHDF5_WASM_CORPUS=conformance/.cache/corpus cargo test -p
clawhdf5-wasm --test lazy` compares every corpus file read lazily with the
same file read from bytes.

Built without `mmap` and `parallel` and without the Zstd and SZIP filters
(they link C): such datasets fail with `unsupported filter`. No C is
compiled; `publish = false` (it is distributed as the package
`build.sh` makes).

## License

MIT