Resumen

El proyecto typeorm-iris ofrece soporte experimental para integrar TypeORM con InterSystems IRIS, permitiendo a los desarrolladores interactuar con IRIS usando los conocidos decoradores y abstracciones de repositorio de TypeORM. Esto ofrece una experiencia de desarrollo más familiar para los desarrolladores de JavaScript y TypeScript que crean aplicaciones Node.js con IRIS como base de datos backend.

Aunque el proyecto implementa los puntos clave de integración con TypeORM y soporta operaciones básicas con entidades, aún no está probado a fondo ni es adecuado para entornos de producción.

¿Por qué typeorm-iris?

El driver oficial de InterSystems IRIS para Node.js no proporciona ejecución nativa de consultas SQL como lo hacen otros drivers de bases de datos (por ejemplo, para PostgreSQL o MySQL). En su lugar, debéis usar una API basada en ObjectScript (por ejemplo, %SQL.Statement) para preparar y ejecutar comandos SQL.

Esto se vuelve problemático al construir aplicaciones modernas que dependen de herramientas ORM como TypeORM. TypeORM espera un driver de bajo nivel capaz de preparar y ejecutar SQL en bruto en una sesión de conexión única, algo que actualmente no está disponible con las herramientas JavaScript de IRIS.

Para superar estas limitaciones, typeorm-iris implementa las piezas necesarias para conectar IRIS y TypeORM, usando bajo el capó las interfaces de ejecución SQL disponibles en ObjectScript.

Fase Inicial y Problemas Conocidos

Este proyecto está en su fase inicial y solo se ha probado con un número limitado de casos. Esperad inestabilidad, funciones faltantes y cambios incompatibles en futuras versiones.

Limitaciones notables observadas durante el desarrollo incluyen:

1. Excesivos viajes de ida y vuelta en la red

Ejecutar SQL a través de la clase %SQL.Statement desde JavaScript implica múltiples mensajes de red entre el proceso Node.js y el servidor IRIS. Por ejemplo, una sola operación lógica de SQL puede requerir varios pasos como:

• Preparar la sentencia
• Ejecutar la consulta
• Obtener metadatos
• Obtener filas individualmente

Cada uno de estos puede generar mensajes separados en la red, resultando en una sobrecarga mucho mayor comparado con el uso de un driver SQL nativo.

2. No hay soporte real para asincronía o ejecución paralela

El driver oficial de IRIS para Node.js no soporta el uso asíncrono en contextos multihilo o basados en workers:

• Reconectar en el mismo proceso suele fallar o causar comportamientos impredecibles.
• Crear hilos workers y usar el driver dentro de ellos genera problemas.
• Solo una conexión por proceso funciona de manera fiable.

Estas limitaciones hacen que no sea adecuado para aplicaciones Node.js modernas y concurrentes. En la práctica, esto limita la capacidad del driver para escalar con cargas de trabajo concurrentes y restringe significativamente las opciones arquitectónicas.

Guía de uso

Debido al uso de las últimas características SQL de IRIS, se requiere IRIS 2025.1 o superior para que funcione.

Podéis instalar typeorm-iris mediante npm:

npm install typeorm-iris

Como este driver no está soportado oficialmente por TypeORM, usarlo requiere una solución alternativa para configurar el DataSource. No podéis usar directamente new DataSource() ni createConnection() como haríais con los drivers oficiales.

Configuración personalizada del DataSource

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
}

Una vez inicializado, podéis usar los decoradores de TypeORM como de costumbre:

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

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

    @Column()
    name: string

    @Column()
    email: string
}

El uso de repositorios funciona de manera similar:

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

Proyectos de ejemplo

El repositorio de GitHub incluye una carpeta sample/ con varios ejemplos completamente funcionales:

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

Estos cubren características básicas de persistencia, relaciones y esquema, ofreciendo demostraciones prácticas de uso.

Tests Unitarios

Las pruebas iniciales incluyen los siguientes casos de uso:

Modelo de Entidad

• debería guardar con éxito y usar métodos estáticos correctamente
• debería recargar la entidad dada con éxito
• debería recargar exactamente la misma entidad
• debería hacer upsert con éxito

Esquema de Entidad > Índices

• básico

Persistencia

• funcionalidad básica
• actualización de entidad
• insertar > actualizar columnas de relación después de la inserción
• muchos a muchos
• uno a uno

Estas pruebas son limitadas en alcance y se añadirá mayor cobertura a medida que el proyecto madure.

Características soportadas

• Decoradores de entidad: @Entity(), @Column(), @PrimaryGeneratedColumn()
• Repositorios: create, save, find, delete, etc.
• Eliminación y sincronización de esquema (experimental)
• Soporte parcial para relaciones y consultas personalizadas

De nuevo, estas características están en fase inicial y pueden no cubrir todo el rango de capacidades de TypeORM.

Limitaciones del mundo real

Limitaciones del driver Node.js de InterSystems IRIS

• Solo una conexión usable por proceso
• No hay soporte adecuado para operaciones paralelas o multihilo
• Falta de soporte para API SQL nativa (vía protocolo SQL)
• Gran dependencia de la comunicación basada en mensajes usando un protocolo propietario

Hasta que InterSystems actualice el driver oficial con soporte para la ejecución correcta de SQL y operaciones concurrentes, este proyecto estará fundamentalmente limitado en términos de rendimiento y escalabilidad.

Comentarios y contribuciones

Como este es un driver experimental, vuestro feedback es crucial. Ya sea que lo probéis en un proyecto pequeño o lo evaluéis para un uso más amplio, por favor compartid problemas y sugerencias en GitHub:

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

Se aceptan pull requests, casos de prueba y mejoras en la documentación.

¿Qué es lo siguiente?

Mejoras futuras planificadas incluyen:

• Ampliar la cobertura de pruebas para consultas y diseños de esquema del mundo real
• Gestionar más características del generador de consultas de TypeORM
• Investigar optimizaciones por lotes
• Mejorar la introspección de esquemas para migraciones

Conclusión

typeorm-iris aporta un soporte muy necesario de TypeORM para desarrolladores Node.js que trabajan con InterSystems IRIS. Aunque hoy no está listo para producción y hereda limitaciones severas de la infraestructura actual del driver, ofrece una base para más experimentación y una posible adopción más amplia en la comunidad de desarrolladores de IRIS.

Si sois desarrolladores de IRIS que queréis integrar con un backend moderno en Node.js usando TypeORM, este es el punto de partida.

Y si os ha parecido útil, ¡por favor votad por ello en el concurso de herramientas para desarrolladores de InterSystems!