Introducing typeorm-iris: TypeORM for InterSystems IRIS from Node.js

Overview

The typeorm-iris project provides experimental support for integrating TypeORM with InterSystems IRIS, enabling developers to interact with IRIS using TypeORM’s well-known decorators and repository abstractions. This allows a more familiar development experience for JavaScript and TypeScript developers building Node.js applications with IRIS as the backend database.

While the project implements key integration points with TypeORM and supports basic entity operations, it’s not yet battle-tested or suitable for production environments.

Why typeorm-iris?

The official InterSystems IRIS Node.js driver does not provide native SQL query execution in the way that other database drivers (e.g., for PostgreSQL or MySQL) do. Instead, you must use an ObjectScript-based API (e.g., %SQL.Statement) to prepare and execute SQL commands.

This becomes problematic when building modern applications that rely on Object-Relational Mapping (ORM) tools like TypeORM. TypeORM expects a lower-level driver capable of preparing and executing raw SQL in a single connection session, which is not currently available with IRIS’s JavaScript tooling.

To overcome these limitations, typeorm-iris implements the necessary pieces to bridge IRIS and TypeORM, using the available ObjectScript SQL execution interfaces under the hood.

Early Stage & Known Issues

This project is in its initial phase and has only been tested with a limited number of cases. Expect instability, missing features, and breaking changes in future iterations.

Notable limitations observed during development include:

1. Excessive Network Roundtrips

Executing SQL through the %SQL.Statement class from JavaScript involves multiple network messages between the Node.js process and the IRIS server. For example, a single logical SQL operation may require multiple steps like:

• Preparing the statement
• Executing the query
• Fetching metadata
• Fetching rows individually

Each of these can result in separate messages over the network, resulting in significantly more overhead compared to using a native SQL driver.

2. No True Async/Parallel Support

The official IRIS Node.js driver does not support asynchronous usage in a multithreaded or worker-based context:

• Reconnecting in the same process often fails or causes unpredictable behavior.
• Spawning worker threads and using the driver inside them leads to issues.
• Only one connection per process works reliably.

These constraints make it unsuitable for modern concurrent Node.js applications. In practice, this limits how well the driver can scale with concurrent workloads, and it significantly restricts architectural choices.

Usage Guide

Due to usage of latest IRIS SQL Fatures requires IRIS 2025.1+ to work.

You can install typeorm-iris via npm:

npm install typeorm-iris

Because this driver is not officially supported by TypeORM, using it requires a workaround for setting up the DataSource. You cannot directly use new DataSource() or createConnection() as you would with official drivers.

Custom DataSource Setup

import { IRISDataSource, IRISConnectionOptions } from "typeorm-iris"

const dataSourceOptions: IRISConnectionOptions = {
    name: "iris",
    type: "iris",
    host: "localhost",
    port: 1972,
    username: "_SYSTEM",
    password: "SYS",
    namespace: "USER",
    logging: true,
    dropSchema: true,
}

export function createDataSource(options: any): IRISDataSource {
    // @ts-ignore
    const dataSource = new IRISDataSource({ ...dataSourceOptions, ...options })
    return dataSource
}

Once initialized, you can use TypeORM decorators as usual:

import { Entity, PrimaryGeneratedColumn, Column } from "typeorm"

@Entity()
export class User {
    @PrimaryGeneratedColumn()
    id: number

    @Column()
    name: string

    @Column()
    email: string
}

Using repositories works similarly:

const userRepository = dataSource.getRepository(User)
const newUser = userRepository.create({ name: "Alice", email: "alice@example.com" })
await userRepository.save(newUser)

Sample Projects

The GitHub repository includes a sample/ folder with several fully working examples:

• sample1-simple-entity
• sample2-one-to-one
• sample3-many-to-one
• sample4-many-to-many
• sample16-indexes

These cover basic persistence, relationships, and schema features, offering practical usage demonstrations.

Unit Tests

Initial testing includes the following use cases:

Entity Model

• should save successfully and use static methods successfully
• should reload given entity successfully
• should reload exactly the same entity
• should upsert successfully

Entity Schema > Indices

• basic

Persistence

• basic functionality
• entity updation
• insert > update-relation-columns-after-insertion
• many-to-many
• one-to-one

These tests are limited in scope and more coverage will be added as the project matures.

Supported Features

• Entity decorators: @Entity(), @Column(), @PrimaryGeneratedColumn()
• Repositories: create, save, find, delete, etc.
• Schema drop and sync (experimental)
• Partial support for relations and custom queries

Again, these features are early-stage and may not cover the full range of TypeORM’s capabilities.

Real-World Constraints

InterSystems IRIS Node.js Driver Limitations

• Only one usable connection per process
• No proper support for parallel operations or threading
• Lack of native SQL API support (via SQL protocol)
• Heavy reliance on message-based communication using proprietary protocol

Until InterSystems updates the official driver with support for proper SQL execution and concurrent operations, this project will be fundamentally limited in terms of performance and scalability.

Feedback & Contribution

As this is an experimental driver, your feedback is crucial. Whether you're trying it out for a small side project or evaluating it for broader use, please share issues and suggestions on GitHub:

➡️ github.com/caretdev/typeorm-iris/issues

Pull requests, test cases, and documentation improvements are welcome.

What's Next

Planned future improvements include:

• Expanding test coverage for real-world queries and schema designs
• Handling more TypeORM query builder features
• Investigating batching optimizations
• Improving schema introspection for migrations

Conclusion

typeorm-iris brings much-needed TypeORM support to InterSystems IRIS for Node.js developers. While it’s not production-ready today and inherits severe limitations from the current driver infrastructure, it provides a foundation for further experimentation and potentially wider adoption in the IRIS developer community.

If you're an IRIS developer looking to integrate with a modern Node.js backend using TypeORM, this is the starting point.

And if you found this useful, please vote for it in the InterSystems Developer Tools Contest!