Chilkat for Node.js

Install

The package name says which Node.js version and platform it is for. For Node.js 26 on 64-bit Windows:

npm install @chilkat/ck-node26-win64

Load it with require, using the name of the package you installed:

const chilkat = require('@chilkat/ck-node26-win64');

Packages

Each name links to the package on npmjs.com.

npm refuses to install a package on an operating system or CPU other than the one in its name (the os and cpu fields of the package), and warns when the Node.js version does not match (the engines field). Each package also contains license.pdf and THIRD-PARTY-NOTICES.txt.

Quick start

const chilkat = require('@chilkat/ck-node26-win64');

// Once per process, before using any other Chilkat object.
// Any string starts the fully functional 30-day trial.
const glob = new chilkat.Global();
if (!glob.UnlockBundle('Anything for 30-day trial')) {
    console.log(glob.LastErrorText);
    process.exit(1);
}

const http = new chilkat.Http();
http.ConnectTimeout = 30;

const html = http.QuickGetStr('https://www.chilkatsoft.com/');
if (html === null) {
    console.log(http.LastErrorText);   // why it failed
} else {
    console.log('HTTP ' + http.LastStatus + ', ' + html.length + ' characters');
}

Chilkat methods do not throw when an operation fails. A method that returns success or failure returns true or false; a method that returns a string or an object returns null on failure. In every case the object's LastErrorText property explains what happened.

One project, several platforms

For a project that is developed on one platform and deployed on another, list the packages as optionalDependencies in package.json. npm install then installs the one that matches the machine it runs on and skips the others:

"optionalDependencies": {
    "@chilkat/ck-node26-win64": "^11.7.0",
    "@chilkat/ck-node26-linux-x64": "^11.7.0",
    "@chilkat/ck-node26-linux-arm64": "^11.7.0",
    "@chilkat/ck-node26-mac-universal": "^11.7.0"
}

and build the package name at run time:

const major = process.versions.node.split('.')[0];
const platform = {
    win32: 'win64',
    darwin: 'mac-universal',
    linux: 'linux-' + process.arch        // linux-x64, linux-arm64 or linux-arm
}[process.platform];
const chilkat = require('@chilkat/ck-node' + major + '-' + platform);

The Chilkat API in JavaScript

Objects are released by the garbage collector. The addon can also be loaded in worker_threads; use a Chilkat object from one thread at a time.

Async methods

A Chilkat method call is synchronous: it blocks the Node.js event loop until it returns. That is fine for quick operations (JSON, XML, hashing, encoding). For network and file operations, use the method's Async form, which exists for every method that can take a while (QuickGetStrAsync, DownloadAsync, ConnectAsync, …). It takes the same arguments and returns a chilkat.Task. task.Run(callback) runs the call on a background thread and calls the function when it has finished; the event loop stays free in the meantime.

const http = new chilkat.Http();

const task = http.QuickGetStrAsync('https://www.chilkatsoft.com/');
if (task === null) {
    console.log(http.LastErrorText);
    process.exit(1);
}

task.Run(function () {
    if (task.TaskSuccess) {
        const html = task.GetResultString();      // what QuickGetStr would have returned
        console.log(html.length + ' characters');
    } else {
        console.log(task.ResultErrorText);        // the LastErrorText of the call
    }
});

The result is read with the method that matches the return type of the synchronous method: GetResultBool, GetResultInt, GetResultString or GetResultBytes. Until the task has finished, do not call other methods on the object it was started from.

A Task is not a JavaScript Promise and cannot be awaited directly. To use await, wrap Run:

function runTask(task) {
    return new Promise(function (resolve) { task.Run(resolve); });
}

// in an async function:
const task = http.DownloadAsync(url, localPath);
await runTask(task);
if (!task.TaskSuccess || !task.GetResultBool()) console.log(task.ResultErrorText);

While a task runs, its PercentDone property gives the progress (0 to 100) for methods that report progress, and Cancel() stops it; a cancelled task finishes with Status "aborted".

const timer = setInterval(function () { console.log(task.PercentDone + '%'); }, 500);
process.once('SIGINT', function () { task.Cancel(); });      // Ctrl+C cancels the download

await runTask(task);
clearInterval(timer);

Progress events

The classes that have events (Http, Ftp2, SFtp, Zip, MailMan, Imap, …) have three callback properties. Assign a function to receive the event, and null to remove it. The callbacks are called during a synchronous method call:

const http = new chilkat.Http();
http.HeartbeatMs = 250;

http.PercentDone = function (pct) {            // 1 .. 100
    process.stdout.write(pct + '%\r');
    return false;                              // true aborts the method in progress
};
http.AbortCheck = function () {                // called about every HeartbeatMs milliseconds
    return Date.now() > deadline;              // true aborts
};
http.ProgressInfo = function (name, value) {   // informational name/value pairs
};

const success = http.Download(url, localPath);

The callbacks are not called while a Task runs in the background. For an Async call, use the task's PercentDone property and Cancel() as shown above.

Licensing

This is the full-version Chilkat product. Chilkat is fully functional for a 30-day evaluation; passing any string to UnlockBundle starts the trial, and a purchased unlock code removes the time limit. The license terms are in license.pdf in every package. For questions, contact Chilkat support.