Présentation de typeorm-iris: TypeORM pour InterSystems IRIS à partir de Node.js

Aperçu

Le projet typeorm-iris fournit une prise en charge expérimentale pour l'intégration de TypeORM avec InterSystems IRIS, permettant aux développeurs d'interagir avec IRIS à l'aide des décorateurs et des abstractions de référentiel bien connus de TypeORM. Cela offre une expérience de développement plus familière aux développeurs JavaScript et TypeScript qui créent des applications Node.js avec IRIS comme base de données backend.

Bien que le projet mette en œuvre des éléments clés d'intégration avec TypeORM et prenne en charge les opérations de base sur les entités, il n'a pas encore été testé en conditions réelles et n'est pas adapté aux environnements de production.

Pourquoi typeorm-iris?

Le pilote officiel InterSystems IRIS Node.js ne permet pas d'exécuter des requêtes SQL natives , contrairement à d'autres pilotes de base de données (par exemple, PostgreSQL ou MySQL). Au lieu de cela, vous devez utiliser une API basée sur ObjectScript (par exemple, %SQL.Statement) pour préparer et exécuter les commandes SQL.

Cela pose problème lors du développement d'applications modernes qui s'appuient sur des outils de mappage objet-relationnel (ORM) tels que TypeORM. TypeORM nécessite un pilote de niveau inférieur capable de préparer et d'exécuter du code SQL brut dans une seule session de connexion, ce qui n'est actuellement pas possible avec les outils JavaScript d'IRIS.

Pour surmonter ces limitations, typeorm-iris implémente les éléments nécessaires pour faire le pont entre IRIS et TypeORM, en utilisant les interfaces d'exécution SQL ObjectScript disponibles en arrière-plan.

Phase initiale & problèmes connus

Ce projet en est à la phase initiale et n'a été testé que sur quelques cas. Il faut s'attendre à une certaine instabilité, à des fonctionnalités manquantes et à des changements importants dans les prochaines versions.

Les limitations importantes observées au cours du développement sont les suivantes:

1. Allers-retours excessifs en réseau

L'exécution de SQL via la classe %SQL.Statement à partir de JavaScript implique plusieurs messages réseau entre le processus Node.js et le serveur IRIS. Par exemple, une seule opération SQL logique peut nécessiter plusieurs étapes, telles que:

• Preparation de l'instruction
• Exécution de la requête
• Récupération des métadonnées
• Récupération de lignes de manière individuelle

Chacun d'entre eux peut générer des messages distincts sur le réseau, ce qui entraîne une surcharge considérable par rapport à l'utilisation d'un pilote SQL natif.

2. Aucune prise en charge de l'asynchronisme/du parallélisme véritable

Le pilote IRIS Node.js officiel ne prend pas en charge l'utilisation asynchrone dans un contexte multithread ou basé sur le travail:

• La reconnexion dans le même processus échoue souvent ou provoque un comportement imprévisible.
• La création de threads de travail et l'utilisation du pilote à l'intérieur de ceux-ci entraînent des problèmes.
• Que une seul connexion par processus fonctionne de manière fiable.

Ces contraintes rendent ce système inadapté aux applications Node.js modernes qui traitent des tâches simultanées. Cette situation limite considérablement la capacité du pilote à s'adapter à des charges de travail simultanées et restreint considérablement les choix architecturaux.

Guide d'utilization

En raison de l'utilisation des dernières fonctionnalités IRIS SQL, il est nécessaire de disposer d'IRIS 2025.1+ pour fonctionner.

Vous pouvez installer typeorm-iris avec npm:

npm install typeorm-iris

Comme ce pilote n'est pas officiellement pris en charge par TypeORM, son utilisation nécessite une solution de remplacement pour configurer le DataSource. Vous ne pouvez pas utiliser directement new DataSource() ou createConnection() comme vous le feriez avec les pilotes officiels.

Configuration personnalisée de la source de données

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
}

Lorsque l'initialisation est terminée, vous pouvez utiliser les décorateurs TypeORM comme d'habitude:

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

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

    @Column()
    name: string

    @Column()
    email: string
}

Il en va de même pour les référentiels:

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

Exemples de projets

Le référentiel GitHub comprend un dossier sample/ qui contient plusieurs exemples fonctionnels:

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

Celles-ci traitent des fonctionnalités de base en matière de persistance, de relations et de schémas, et présentent des exemples d'utilisation pratique.

Tests unitaires

Les tests initiaux comprennent les cas d'utilisation suivants :

Modèle d'entité

• doit enregistrer et utiliser de manière appropriée les méthodes statiques
• doit recharger correctement l'entité donnée
• doit recharger exactement la même entité
• doit effectuer correctement un upsert

Schéma d'entité > Index

• basique

Persistance

• fonctionnalité basique
• mise à jour d'entité
• insertion > update-relation-columns-after-insertion (mise à jour des colonnes de relation après insertion)
• plusieurs-à-plusieurs
• en individuel

Ces tests ont une portée limitée et leur couverture sera élargie au fur et à mesure de l'avancement du projet.

Fonctionnalités prises en charge

• Décorateurs d'entités: @Entity(), @Column(), @PrimaryGeneratedColumn()
• Référentiels: create, save, find, delete, etc.
• Suppression et synchronisation du schéma (expérimental)
• Prise en charge partielle des relations et des requêtes personnalisées

Attention, ces fonctionnalités sont encore en phase initiale et peuvent ne pas couvrir l'ensemble des capacités de TypeORM.

Limitations réelles

Limitations liées au pilote Node.js d'InterSystems IRIS

• Une seule connexion utilisable par processus
• Pas de prise en charge adéquate des opérations parallèles ou du threading
• Absence de prise en charge native de l'API SQL (via le protocole SQL)
• Dépendance importante à la communication par messages utilisant un protocole propriétaire

Tant qu'InterSystems n'aura pas mis à jour le pilote officiel afin d'assurer la prise en charge de l'exécution SQL et des opérations simultanées, ce projet restera très limité en termes de performances et d'évolutivité.

Commentaires & Contributions

Comme il s'agit d'un pilote expérimental, vos commentaires sont essentiels. Que vous l'essayiez pour un petit projet parallèle ou que vous l'évaluiez en vue d'une utilisation plus large, n'hésitez pas à partager vos problèmes et suggestions sur GitHub:

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

Les pull requests, les cas de test et les améliorations de la documentation sont appréciés.

À venir

Les améliorations prévues incluent:

• Élargissement de la couverture des tests pour les requêtes réelles et les conceptions de schémas
• Prise en charge d'un plus grand nombre de fonctionnalités du générateur de requêtes TypeORM
• Analyse des optimisations par lots
• Amélioration de l'introspection des schémas pour les migrations

Conclusion

typeorm-iris apporte un soutien indispensable de TypeORM à InterSystems IRIS pour les développeurs Node.js. Bien qu'il ne soit pas encore prêt pour la production et qu'il hérite des limitations importantes de l'infrastructure actuelle du pilote, il constitue une base pour poursuivre l'expérimentation et potentiellement élargir son adoption au sein de la communauté des développeurs IRIS.

Si vous êtes un développeur IRIS et cherchez à intégrer un backend Node.js moderne à l'aide de TypeORM, c'est le point de départ idéal.

Et si vous avez trouvé cela utile, n'hésitez pas à voter à pour cette solution dans le concours InterSystems Developer Tools Contest!