Connecting to InterSystems IRIS With Node.js

JavaScript and TypeScript back-ends running on Node.js can connect to InterSystems IRIS using several available tools. The official InterSystems IRIS native SDK is @intersystems/intersystems-iris-native.

To use the Node.js SDK, first install Node.js (see the Node.js Website for instructions). Then, start a new project in a suitable directory with:

npm init -y

The -y flag is not required, but skips interactive questions about the project, like package name, description and version.

To install the InterSystems IRIS SDK, run:

npm install @intersystems/intersystems-iris-native

To use the package, you can either use ES Module syntax ( import), or commonjs syntax ( require). The npm default is the commonjs syntax. For this use:

const irisnative = require("@intersystems/intersystems-iris-native");

If you'd prefer to use ES Module syntax, change the type value in the package.json file as follows:

    "type":"module", 

With ES Module syntax set, you can import the package with import:

import * as irisnative from "@intersystems/intersystems-iris-native";

To connect to an instance of InterSystems IRIS, first ensure the instance is running. You will need the standard connection credentials of server (or host), superserver port (default is 1972), namespace, username and password. The example below shows the connection to an instance of InterSystems IRIS community running locally.

// Import the irisnative package
import * as irisnative from "@intersystems/intersystems-iris-native";

// Create the connection
const connection = irisnative.createConnection({
    host:'localhost', // Server
    port:1972, // Port
    ns:'USER', // Namespace
    user:'SuperUser', // Username
    pwd:'SYS' // Password
  })

if (connection){
    console.log("Connection Made!")
}

// Close the connection
connection.close()

To use this example, save the code into a file called demo.js in the directory where the npm package was created. Then, with the terminal open in this directory, run:

node ./demo.js

To access globals, create an irisjs object using connection.createIris(). Then use standard .set() and .get() methods.

// Create irisjs object
const irisjs = connection.createIris()

// Set a Global 
// Syntax : irisjs.set("Value", "GlobalName", "subscript1", "subscript2" )

irisjs.set('Hello World!','Test',1) // Equivalent to: Set ^Test(1) = "Hello World!"

// Get a Global 
// Syntax: irisjs.get("GlobalName", "subscript1", "subscript2" )

const globalValue = irisjs.get('Test',1) // Accessing ^Test(1) 

console.log(globalValue) // Outputs "Hello World!"

To test this snippet, copy it into the demo.js file above, before the connection.close() call. Then run the file again with node ./demo.js.

The  irisjs object to can also access IRIS classes and methods. You call class methods using  irisjs.classMethodValue or  irisjs.classMethodVoid, where value and void specify whether anything is returned from the class method.

If you need specific return types, you also used  irispy.classMethodString, or replace  String with another datatype.

For example, if we had the following class in our instance of InterSystems IRIS (for information on how to load this into your IRIS instance see Setting Up Your Development Environment in VSCode).

Class sample.DemoClass 
{
ClassMethod AddNumbers(a As %Integer, b As %Integer) As %Integer
{
	return a+b	
}
ClassMethod IncrementGlobal(value As %String) As %Status
{
	set ^DemoGlobal($INCREMENT(^DemoGlobal)) = value
}
}

We could use the following code to access the Class Methods. Again, you can test this snippet by adding it to the demo.js file.

// See above for connection
const irisjs = connection.createIris()
console.log(irisjs)

const number_sum = irisjs.classMethodNumber("sample.DemoClass", "AddNumbers", 1, 2) 
console.log(`The sum of 1 and 2 is ${number_sum}`) // prints "The sum of 1 and 2 is 3"

// Sets the first integer subscript of a global to "Hello World"
irisjs.classMethodVoid("sample.DemoClass", "IncrementGlobal", "Hello World")

console.log(irisjs.get("DemoGlobal")) // Prints 1 (or the number of times IncrementGlobal has been run)

console.log(irisjs.get("DemoGlobal", 1)) // Prints "Hello World"

You can use irisjs.classMethodObject() to instantiate a class object, for example, say you had the IRIS class:

Class sample.Person Extends %Persistent
{

	Property Name As %String;
	
	Property Age As %Integer;
	
	Method setName(name As %String) As %Status{
		set ..Name = name
		return $$$OK
	}
	
	Method addYears(num as %Integer) As %Integer {
		return ..Age + num
	}
}

You could use this from a node application with:

// Create an instance of the Person class
const person = irisjs.classMethodObject("sample.Person", "%New")

// Set property with .set(property, value)
person.set("Age", 25)

// Get property with .get(property)
console.log(`Person's age is ${person.get("Age")}`) 

// Call method without returning a value with .invokeVoid(methodName, arg1, arg2, ...)
person.invokeVoid("setName", "Alison Turner")

console.log(`Person's name is ${person.get("Name")}`) 

// Call method with return value with .invoke(methodName, arg1, arg2, ...)
const new_age = person.invoke("addYears", 5)

console.log(`New age is ${new_age}`) 

// Save the object by invoking the %Save method
person.invokeVoid("%Save")

This block of code would output the following:

Person's age is 25
Person's name is Alison Turner
New age is 30

There are several community libraries that can integrate with InterSystems IRIS, providing different experiences which may improve the efficiency of certain functions. Please note, these are not supported by InterSystems, so use at your own risk

• TypeORM-IRIS By CaretDev. This library connects to InterSystems IRIS using a the TypeORM framework, allowing better access to databases with SQL.
  
• mg-dbx/  mg-dbx-napi by MGateway Ltd