Install the stable release.
Use Node.js 22 or 24. EASI JS 1.0.0 ships as native ES modules with no required npm runtime dependencies. In a new project folder, run:
npm init -y
npm install @xinonix/easi-jsSave the example below as quickstart.mjs. The .mjs extension tells Node to use ES modules, so the imports and top-level await work without extra configuration. You can also set "type": "module" in a project’s package.json.
For a reproducible installation of this release, use npm install @xinonix/easi-js@1.0.0.
Give a pipeline some metadata.
This example creates a small DICOM JSON record. Its eight-digit keys are DICOM tags; vr describes each attribute’s value representation, and Value holds its values. These are synthetic identifiers for learning.
import EASI, { Tag } from '@xinonix/easi-js';
const metadata = {
'00080016': { vr: 'UI', Value: ['1.2.840.10008.5.1.4.1.1.7'] },
'00080018': { vr: 'UI', Value: ['2.25.123.1.1'] },
'00080050': { vr: 'SH', Value: ['SYNTHETIC-ACCESSION'] },
'00080060': { vr: 'CS', Value: ['OT'] },
'00100020': { vr: 'LO', Value: ['SYNTHETIC-PATIENT'] },
'0020000D': { vr: 'UI', Value: ['2.25.123'] },
'0020000E': { vr: 'UI', Value: ['2.25.123.1'] }
};
const source = new TextEncoder().encode(JSON.stringify(metadata));
const result = await EASI.pipelineBuilder()
.fromByteStream()
.ofDicomMetadata()
.toInstances()
.build()
.process({ source });
const instance = result.first();
console.log(JSON.stringify({
instances: result.count,
patientId: instance.dataSet.value(Tag.PatientID),
studyUid: instance.dataSet.value(Tag.StudyInstanceUID),
instanceUid: instance.dataSet.value(Tag.SOPInstanceUID)
}, null, 2));node quickstart.mjsYou should see one instance and its identifiers:
{
"instances": 1,
"patientId": "SYNTHETIC-PATIENT",
"studyUid": "2.25.123",
"instanceUid": "2.25.123.1.1"
}You do not need Orthanc, a PACS connection, a patient image, or a pixel codec. The input is metadata, and the output is a DICOM instance object in your application.
Read the chain from top to bottom.
| Stage | What it does |
|---|---|
fromByteStream() | Accepts the encoded bytes we created in memory. |
ofDicomMetadata() | Parses DICOM JSON metadata. |
toInstances() | Builds the DICOM object model. |
build() | Connects the reader, parser, and output handler. |
process({ source }) | Processes this input and returns a result collection. |
result.count counts the products returned by the pipeline. result.first() gets the first product; result.toArray() gives you a plain array when there are multiple products.
An instance’s dataSet contains its attributes. Use the library’s Tag objects to access them: Tag.PatientID names the patient identifier attribute, and Tag.StudyInstanceUID names the study’s unique identifier. Study, series, and instance UIDs form DICOM’s imaging hierarchy.
For an optional attribute, dataSet.value(tag, fallback) lets you supply a fallback. Check dataSet.has(tag) when presence itself matters.
Change the input when you are ready.
To read native DICOM bytes already in memory, keep fromByteStream() and change the format to ofDicomData(). For a Node filesystem path, choose fromFileStream() and pass the path as source. The next guide explains how those choices fit together.
Browser applications can use the core pipeline with a bundler or an import map, plus browser-compatible sources such as a File, Blob, or byte array. A bare npm import needs package resolution; a local filesystem path and DIMSE transport require Node.js.
For file, browser, XML, and HTTP recipes, open the package’s input guide.
Choose the output your app needs
Select a handful of attributes or write DICOM bytes using the same pipeline pattern.