@ifc-x/convert

@ifc-x/convert

A JavaScript library and CLI tool for converting IFC/FRAG files into formats like SQLite/FRAG and (SOON) Excel. Supports both Node.js and browser environments.

Features

• Convert IFC models into structured SQLite or Excel files
• Works in Node.js and browser environments
• CLI utility for quick conversions
• Progress tracking and middleware support
• Extensible with custom readers and writers

Installation

npm install @ifc-x/convert

For global CLI usage:

npm install -g @ifc-x/convert

Usage

CLI

ifc-x-convert <input.ifc> <output.db>

Example:

ifc-x-convert model.ifc model.sqlite

This reads an IFC file and writes the result as SQLite. Progress updates are printed to the console.

Library

Quick Convert

import { convert } from "@ifc-x/convert";

const result = await convert("path/to/model.ifc", {
  inputType: "ifc",
  outputType: "sqlite",
  progressCallback: (p) => console.log(`Progress: ${p}%`),
});

// result is a Uint8Array, ready to be saved

Custom Converter with Middleware

import { Converter } from "@ifc-x/convert";

const converter = new Converter();

// Example middleware: modify data before writing
converter.use(async (data) => {
  // custom transformation
  return data;
});

const ifcBytes = new Uint8Array(/* ... */);

const result = await converter.convert(ifcBytes, {
  inputType: "ifc",
  outputType: "sqlite",
});

API

convert(input, options)

Convert a file or buffer using the global registry.

• input: string | File | Blob | ArrayBuffer | Uint8Array

• options:

  • inputType (string) – type of input (e.g., ifc, frag)
  • outputType (string) – type of output (e.g., sqlite, xlsx)
  • env ("node" | "browser") – execution environment
  • readerClass (Function) – force a specific reader
  • writerClass (Function) – force a specific writer
  • middleware (Function[]) – array of transformation functions
  • progressCallback (Function) – progress updates (0–100)

Returns: Promise<Uint8Array>

Converter

Class for advanced conversion workflows.

new Converter(options)

• env: "node" or "browser"
• readerClass: custom reader
• writerClass: custom writer

Methods

• use(fn) – add a middleware function
• detectType(input) – detect file type
• convert(input, options) – perform conversion

registry

A global registry that manages available readers and writers. The converter uses it to automatically detect the best match for a given environment and format.

Methods

• addReader(readerClass) – register a new reader class
• addWriter(writerClass) – register a new writer class
• findReader(env, type) – find the best reader for an environment and input type
• findWriter(env, format) – find the best writer for an environment and output format

Readers and writers must define:

• environments: array of supported environments (["node"], ["browser"], or both)
• formats: array of supported formats (e.g., ["ifc"], ["frag"], ["sqlite"])
• priority: number used to choose between multiple candidates

Example: Registering a custom writer

class CustomExcelWriter {
  static environments = ["node"];
  static formats = ["xlsx"];
  static priority = 10;

  async write(data, options) {
    // implement writing to Excel
    return new Uint8Array();
  }
}

import { registry } from "@ifc-x/convert";

registry.addWriter(CustomExcelWriter);

Development

Scripts

• npm run examples – Run examples
• npm build – Build dist version
• npm test – Run tests

Dependencies

• web-ifc – IFC parser
• sql.js – SQLite in WebAssembly
• sqlite / sqlite3 – SQLite for Node.js

License

MIT © Lauri Tunnela