uml-extractor

A JavaScript library and command line tool that extracts the complete UML class model – packages, classes, attributes, relations and diagrams – from Sparx Systems Enterprise Architect files (.eap, .eapx, .qea, .qeax and EA-produced XMI) into a plain, documented JSON format with stable identifiers, and compares two such outputs.

The library runs in Node and in the browser and takes the file content as a Uint8Array.

Status: all phases of the roadmap are done. Database files (.qea, .qeax, .eap, .eapx) and EA's XMI 2.1 export can be extracted, including diagrams, in Node and in the browser, and two versions of a model can be compared. See plan/ for the goal, architecture and roadmap.

Installation

npm install @entryscape/uml-extractor     # library
npm install -g @entryscape/uml-extractor  # command line tool `uml-extractor`

Requires Node 20.19 or later (or 22.12 or later on Node 22).

Usage

uml-extractor extract model.qea -o model.json
uml-extractor extract model.qea --package Core       # a package and the packages below it
uml-extractor extract model.qea --diagram Overview   # a diagram and what it shows
uml-extractor diff old.json new.qea --format text   # JSON from extract or EA files

Names may be replaced by ids; an ambiguous name is reported with the candidates. Input that cannot be read (not an EA file, a DBMS shortcut, a damaged file) ends with exit code 1 and a message. A model with 5 000 classes, 20 000 attributes, 5 000 connectors and 50 diagrams is extracted in about 2.5 s.

import { extract, toJson } from '@entryscape/uml-extractor';

const model = await extract(bytes, { fileName: 'model.qea' }); // bytes: Uint8Array
const json = toJson(model); // deterministic JSON, see schema/model.schema.json

The package is an ES module. CommonJS code can require() it directly, without a separate build, since Node 20.19 and 22.12 load ES modules that way:

const { readFileSync } = require('node:fs');
const { extract } = require('@entryscape/uml-extractor');

extract(new Uint8Array(readFileSync('model.eap'))).then((model) => {
  // …
});

The JSON Schema of the output is exported as @entryscape/uml-extractor/schema/model.schema.json.

In the browser

pnpm build writes dist/uml-extractor.browser.js with dist/sql-wasm-browser.wasm; tell extract() where the WebAssembly is:

import { extract } from './uml-extractor.browser.js';

const model = await extract(bytes, { locateFile: (file) => `/assets/${file}` });

demo/index.html (after pnpm build) reads a file chosen by the user, directly from disk without a server. To bundle the library yourself, map Node's stream and events to stream-browserify and events, and provide a global process (process/browser.js), as scripts/build.js does; mdb-reader's decryption code needs them.

Development

Requires Node 20.19 or later and pnpm.

pnpm install
pnpm test     # Jest (ES modules)
pnpm lint     # ESLint + Prettier check
pnpm format   # apply Prettier
pnpm build    # browser bundles and the demo page
pnpm update-expected   # regenerate test/fixtures/*/expected.json

License

MIT. No code is taken from the OSLO UML Transformer (MIT), but its EA extractor (oslo-extractor-uml-ea) informed the knowledge of EA's tables, columns and joins (see plan/oslo.md). Fixture 09 is OSLO's model 01-AssociatiesMijnDomein, kept with its licence in test/fixtures/09-oslo/.