InterSystems IRIS Native API for Node.js

!Version

Copyright © 2025, InterSystems Corporation, Boston, MA. All rights reserved.

Introduction

The InterSystems IRIS Native API for Node.js is available as an add-on module for use in Node.js projects. The
implementation of the Node.js InterSystems IRIS Native API uses the same core InterSystems IRIS Native API that is used by the Native APIs for Python, Java, and others.

For documentation, see either the InterSystems IRIS product documentation or the driver's API documentation (also available under /docs/api).

Minimum Requirements

* Node.js version 20.0.0 or later
> InterSystems officially supports the driver on the actively maintained versions of Node.js (currently v20.0.0 or later). Node.js versions that are no longer actively maintained might continue to work, but no official support, patches, or security updates will be provided for these versions. InterSystems recommends using Node.js v20.0.0+ for full support.
* npm v10.9.2 or later (available with Node.js 20.0.0 installations)
* InterSystems IRIS 2019.1 or later

The InterSystems IRIS Native API for Node.js module is distributed with InterSystems IRIS 2025.3 kits.

Dependencies

The InterSystems IRIS Native API for Node.js depends on the following modules:
* decimal.js
* yargs

These dependencies are installed automatically when you install the InterSystems IRIS Native API for Node.js module.

Installation

The InterSystems IRIS Native API for Node.js is available in 2025.3 kits and is built as an npm-installable module.
This module is located under /dev/nodejs. After you install the kit, you can install the module with npm install.

Quickstart Guide

1. Create and navigate to a new directory for the project:

``Shell
mkdir iris-demo
cd iris-demo
`

2. Initialize the project. This creates the package.json project file:

`Shell
npm init --yes
`

3. Install the InterSytems IRIS Native API for Node.js module:

`Shell
npm install --save /dev/nodejs/intersystems-intersystems-iris-native-2.0.3.tar.gz
`

You can now use the Native API module in your applications. The following example demo.js connects to an InterSystems IRIS instance, writes to a global, and deletes the global:

`Javascript
// save as demo.js
const irisnative = require('@intersystems/intersystems-iris-native')

const connection = irisnative.createConnection({
host:'127.0.0.1',
port:1972,
ns:'USER',
user:'username',
pwd:'password'})

const iris = connection.createIris()

iris.set('hello world!','test',1)
console.log(iris.get('test',1))
iris.kill('test',1)
connection.close()
`

You can then run the application with node:

`Shell
node demo.js
`

For more examples, see the module's examples directory.

To run the examples, create a connection.config in the main project installation directory (usually in the node_modules directory of your system or project, which is generated by the standard npm module installation process):

`
> npm run example:configuration --host localhost --port 1972 --ns USER --user yourusername --pwd yourpassword
`

You can change the arguments passed in the script based on your own connection information. You can also omit all arguments to use the defaults.

To get started, see the Quickstart Guide. This is also available in /docs/api/tutorial-quick_start.html.

#### Load the Module

`javascript
const irisnative = require('@intersystems/intersystems-iris-native');
`

#### Get IRIS Connection

To establish a connection to an InterSystems IRIS server, use createConnection(). This takes as an argument the connection information for the server.

For example, to connect to the InterSystems IRIS server at 127.0.0.1 with superserver port 1972 and to start in the USER namespace:
`Javascript
let connectionInfo = {
host: '127.0.0.1',
port: 1972,
ns: 'USER',
user: 'username',
pwd: 'password'
};

const connection = irisnative.createConnection(connectionInfo);
`

createConnection() also supports optional parameters for communicating with InterSystems IRIS with shared memory, configuring connection timeouts, and logging:
- sharedmemory: Boolean, whether to use shared memory, if available, to communicate with InterSystems IRIS (default: true). If shared memory isn't available or if set to false, the driver falls back to TCP.
- timeout: Integer, the amount of time (in milliseconds) before the connection attempt times out (default: 10000 -- 10 seconds).
- logfile: String, the full path and name of a log file for this connection. If not specified or set to - (dash), the driver will not log information about the session. Logging is fairly system-intensive and should only be enabled for debugging.

You can add a prefix the path specified by logfile with certain characters to change logging behavior:
- +: Overwrite existing content, if any, in the log file.
- -:Disable logging.

The following example uses TCP to connect to InterSystems IRIS (even if shared memory is available) and times out after 10 milliseconds. Activity is logged to mylogfile.log:
`Javascript
let connectionInfo = {
host: '127.0.0.1',
port: 1972,
ns: 'USER',
user: 'username',
pwd: 'password',
sharedmemory: false,
timeout: 10,
logfile: 'mylogfile.log'
};
const connection = irisnative.createConnection(connectionInfo);
console.log(connection);
`

The above example produces this output to the console device when a connection is successfully established:

`Shell
Connection {
host: '127.0.0.1',
port: 1972,
ns: 'USER',
timeout: 10,
logfile: 'mylogfile.log' }
`

createConnection() can also be invoked asynchronously by passing in a callback function:

`Javascript
irisnative.createConnection(
connectionInfo, (err,c) => {
if (err) {
console.log('Could not establish connection: ' + err)
} else {
// Connection is successful
if (!c.isClosed()) {
console.log('Connected to host');
const iris = c.createIris();
iris.set('Hello from an asynchronously connected world!','isc.test',1,2);
console.log(iris.get('isc.test',1,2));
} else {
console.log('Connection object instantiated, but the connection to InterSystems IRIS is closed');
}
}
});
// This happens after sending the async request
console.log('Connection request sent to InterSystems IRIS');
`

Documentation

For documentation, see either the InterSystems IRIS product documentation or the driver's API documentation (also available under /docs/api).




$3

The various lock() and unlock() methods accept a lock reference, not a global name. That means that if you intend to lock a global, you must prefix the global name with ^ (caret).

Module Organization

This module is implemented with JavaScript and C++. The project follows the standard structure of simple Node.js projects:

  <installationdir>/intersystems-iris
  ├─┬ bin                        (Add-on binaries and shared libraries)
  │░└─┬  
  │░░░├── irissdk.*
  │░░░├── irisconnect.*
  │░░░├── libcrypto-3.*          (Optional)
  │░░░└── libssl-3.*             (Optional)
  ├─┬ docs
  │░└── api                      (API documentation)           
  ├─┬ examples
  │░├── config   
  │░├─┬  quick_start
  │░│░└── .js code that follows the tutorials   
  │░└── .js sample code   
  ├─┬ src
  │░└── .js files
  │
  ├── package.json      
  ├── README.md                  (This file)
  ├── LICENCE.txt
  └── test-config.js             (Used to produced the ./connection.config)

Logging

This module uses a standard InterSystems IRIS Native connection to the server. To enable logging, provide a log file in your connection arguments.

The following is sample output to the log file test.log:

`Shell
tail test.log

Received: (03/11-18:18:19:410) [ThreadID = 6CB8] [JobNumber = 22232] [DeviceID = 000001FD9B7CE990]
Header:
0000: 00 00 00 00 0B 00 00 00 00 00 00 00 00 CA ..............

Sent: (03/11-18:18:19:440) [ThreadID = 6CB8] [JobNumber = 22232] [DeviceID = 000001FD9B7CE990]
Header:
0000: 00 00 00 00 00 00 00 00 00 00 00 00 44 43 ............DC
`

$3

The following procedure configures a sample application for demonstrating some of the basic concepts from the quickstart guide:

1. Install yargs:
`Shell
npm install --save yargs
`

2. Create the file demo.js with the following content:
`Javascript
console.log('InterSystems IRIS Native API for node.js Demo');

const yargs = require('yargs');

const argv = yargs
.option('host', {
alias: 'h',
default: '127.0.0.1'
})
.option('port', {
alias: 'p',
default: 1972
})
.option('namespace',{
alias: 'ns',
default: 'USER'
})
.option('user',{
alias: 'u',
default: 'username'
})
.option('password',{
alias: 'pwd',
default: 'password'
})
.argv;

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

let connectionInfo = {
host: argv.host,
port: argv.port,
ns: argv.ns,
user: argv.user,
pwd: argv.password
};

console.log('Creating the database connection... ');
console.log(JSON.stringify(connectionInfo))
let connection = iris.createConnection(connectionInfo);

console.log('Creating the IRIS instance... ');
const dbnative = connection.createIris();

dbnative.set('Hello world','globalArray','sub1');
console.log('Created subnode ^globalArray("sub1") with value ' + dbnative.get('globalArray','sub1') + '"');
dbnative.set('value2','globalArray');
console.log('Assigned value "' + dbnative.get('globalArray') + '" to root node.');

// Delete entire global array ^globalArray
dbnative.kill('globalArray');
`

3. Add a start script to package.json:
`Javascript
{
"script": {
.
.
"start": "node demo.js"
}
}
`

4. Run the application using the default arguments:
`Shell
npm start
`

If you need to override any of the default connection parameters, add a -- after npm start and then specify the parameters you want to override. For example, to override the default host 127.0.0.1 and instead connect to the host my.irishost.com:

`Shell
npm start -- --host my.irishost.com
`

This example overrides the host, port, ns, user and pwd parameters:

`Shell
npm start -- --host 127.0.0.1 --port 51774 --ns %SYS --user thisisme --pwd XXX

> irisnodetest@1.0.0 start (your current folder displays here)
> node app.js "--host" "127.0.0.1" "--port" "51774" "--ns" "%SYS" "--user" "thisisme" "--pwd" "XXX"

InterSystems IRIS Native API for node.js Demo
Creating the database connection...
{ host: '127.0.0.1',
port: 51774,
ns: '%SYS',
user: 'thisisme',
pwd: 'XXX' }
Creating the IRIS instance...
Created subnode ^globalArray("sub1") with value Hello world"
Assigned value "value2" to root node.
``