API reference
Arguments, return values, defaults and error behavior for integrating NMRLink. For a step-by-step introduction, start with your first Web UI.
On this page
Browse by feature
- Connection and measurement: NMRController, NMRDevice, parameters, records and timing
- Signal analysis: analyzeMeasurement, correctBaseline and computeSpectrum
- Graphs: NMRGraphs, SVG generation, languages, labels and colors
- Save and load: JSON, PNG, timestamps and scan archives
- Frequency and pulse scans: planning, cancellation, common phase and sine fits
- T1 and T2: pulse settings, delay scans, echo windows and exponential fits
Entry points
| Import | Contents | Environment |
|---|---|---|
| nmrlink | Control, analysis, scans and JSON validation | Browser / Node.js; hardware access depends on the transport |
| nmrlink/graphs | NMRGraphs and SVG generators | NMRGraphs requires a browser; SVG generators also run in Node.js |
| nmrlink/browser | Downloads, File reading, PNG and timestamps | Downloads, File reading and PNG require a browser; timestamp formatting also works in Node.js |
import { NMRController, analyzeMeasurement } from "nmrlink";
import { NMRGraphs } from "nmrlink/graphs";
import { saveMeasurement, readMeasurement } from "nmrlink/browser";For static HTML, use ./nmrlink/index.js, ./nmrlink/graphs.js and ./nmrlink/browser.js according to the installation layout. TypeScript declarations are not included.
Error conventions
- NMRController operations resolve with success or failure objects and also report failures through onError.
- NMRDevice and low-level scan promises reject on failure.
- Synchronous analysis, validation and SVG generators throw for invalid input.
- Measurements are never retried automatically. Scan cancellation waits for the current measurement to finish.
Library-created errors and warnings use English messages and stable codes. Translate UI text using code, not by matching message. Graph locale does not translate diagnostics. Browser/OS failures at operation boundaries retain the original exception in cause.
Error codes and UI translation
Exception classes such as TypeError, RangeError and AggregateError are preserved. Codes are also available through ERROR_CODES. details contains values such as parameter names and bounds. English message wording may improve; do not use it for program logic. cause is present when an underlying exception is retained.
import { ERROR_CODES, analyzeMeasurement } from "nmrlink";
try {
const analysis = analyzeMeasurement(record, { startMs: 5, endMs: 1 });
graphs.show(record, analysis);
} catch (error) {
if (error.code === ERROR_CODES.INVALID_FFT_RANGE) {
status.textContent = "Set FFT end after start, within the acquisition range.";
} else {
status.textContent = "Analysis failed. Check the input.";
console.error(error);
}
}| Example code | Meaning / details |
|---|---|
| INVALID_PARAMETER_RANGE | Parameter out of range; name, minimum, maximum |
| INVALID_FFT_RANGE / INSUFFICIENT_FFT_SAMPLES | Invalid FFT interval / too few samples |
| INVALID_JSON / RECORD_TOO_LARGE | Malformed JSON / measurement JSON too large |
| NO_REFERENCE_SIGNAL | No usable common reference signal |
| DEVICE_NOT_CONNECTED / DEVICE_BUSY | Disconnected / another operation is running |
| WEB_SERIAL_UNAVAILABLE / RESPONSE_TIMEOUT | Unsupported browser API / device response timeout |
| PORT_SELECTION_CANCELLED / SERIAL_PERMISSION_DENIED | Port selection cancelled / access denied |
Use Object.keys(ERROR_CODES) to list the codes. For unknown codes, show a general message in the selected language and retain details in the console. Unknown errors from user callbacks or replacement transports are wrapped with codes at operation boundaries.
Warning codes
analyzePulseCalibration, analyzeT1 and analyzeT2 retain warnings as an array of English strings. The added warningDetails array contains matching { code, message, details } objects in the same order. Use code for translation. Archive parsers recompute derived values, so old JSON without warningDetails can still be loaded.
for (const warning of result.warningDetails) {
console.log(warning.code, warning.message, warning.details);
}
// result.warnings === the same messages as strings (in the same order).See analysis specifications for FFT conventions, normalization, phase and fit models.
The separate nmrlink-server remote API is covered by remote UI integration. Remote operation remains unverified in a real environment.