InterSystems IRIS Native API for Node.js
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:
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 <InterSystems IRIS install directory>/dev/nodejs. After you install the kit, you can install the module with npm install.
Quickstart Guide
-
Create and navigate to a new directory for the project:
mkdir iris-demo
cd iris-demo
-
Initialize the project. This creates the package.json project file:
npm init --yes
-
Install the InterSytems IRIS Native API for Node.js module:
npm install --save <InterSystems IRIS install directory>/dev/nodejs/intersystems-intersystems-iris-native-2.0.2.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:
// 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:
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
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:
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:
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:
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:
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).
Custom Locking Interface for Node.js
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:
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
Run the Demo Application
The following procedure configures a sample application for demonstrating some of the basic concepts from the quickstart guide:
-
Install yargs:
npm install --save yargs
-
Create the file demo.js with the following content:
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');
- Add a start script to
package.json:
{
"script": {
.
.
"start": "node demo.js"
}
}
-
Run the application using the default arguments:
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:
npm start -- --host my.irishost.com
This example overrides the host, port, ns, user and pwd parameters:
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.