JSLink provides a mechanism for Pharo to communicate with libraries and applications implemented in node.js.

• Getting Started
  • Installation
  • First statements
  • Programmatic Use
• Garbage Collection
• Callbacks
• Automated Tests
• ToDo
• Futures
• Acknowledgements and Thanks

Requirements:

JSLink has been tested with:

• Pharo 8
• node.js 12.x

To install JSLink in an existing Gtoolkit image:

EpMonitor disableDuring: [ 
Metacello new
	repository: 'github://feenkcom/gtoolkit-remote/src';
	baseline: 'Gt4JSLink';
	load ]

To install JSLink in a vanilla Pharo image:

EpMonitor disableDuring: [ 
Metacello new
	repository: 'github://feenkcom/JSlink/src';
	baseline: 'JavaScriptLink';
	load ]

When first running JSLink it is worthwhile starting Pharo from the command line so you can monitor the output.

Open a playground in Gtoolkit and start the JSLinkApplication:

This will automatically install all the dependent modules with npm:

$ vmgt/gtoolkit Pharo.image eval --interactive --no-quit "GtWorld open."
GtWorld
[Glutin] Profile #0 worked
[Glutin] Profile #0 worked
loadDep:fsevents → 304    ▌ ╢███████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░╟
WARN engine fsevents@2.1.2: wanted: {"node":"^8.16.0 || ^10.6.0 || >=11.0.0"} (current: {"node":"8.10loadDep:react-is → header ▐ ╢███████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░╟
loadDep:execa → resolveWi ▐ ╢███████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░╟
WARN engine execa@3.4.0: wanted: {"node":"^8.12.0 || >=9.7.0"} (current: {"node":"8.10.0","npm":"3.5.loadDep:strip-final-newli ▐ ╢███████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░╟
WARN engine human-signals@1.1.1: wanted: {"node":">=8.12.0"} (current: {"node":"8.10.0","npm":"3.5.2"
> sqlite3@4.1.1 install /home/alistair/pharo8/so07/pharo-local/iceberg/feenkcom/JSlink/js/node_modules/sqlite3
> node-pre-gyp install --fallback-to-build
...

We now evaluate our first expression in JavaScript:

After typing the code in to the playground it is evaluated by pressing the play & inspect button:

From here we can navigate through the attributes of the object in the same way as when inspecting pharo objects.

If the value of the attribute is a non-primitive object, a proxy will be returned, if it is a primitive, it will be returned directly:

When evaluating statements in a proxy object's playground, this is bound to the proxy object:

The node.js server can then be stopped with:

JSLinkApplication stop.

So far we have been using a global instance of JSLink, however it is possible to have multiple servers running concurrently through the use of private instances.

For this example we'll create an Excel spreadsheet by installing and using the existing excel4node module.

To install the module:

jslink := JSLinkApplication withDefaultSettings.
jslink start.
jslink installModule: 'excel4node'.

JSLink allows JavaScript code to be supplied in two ways:

1. Strings of JavaScript code, and
2. AST objects generated using the JavaScriptGenerator package

First, using strings:

"Start JSLink"
jslink := JSLinkApplication withDefaultSettings.
jslink start.

"Ensure that the 'excel4node' module is installed."
jslink installModule: 'excel4node'

"Create the spreadsheet and worksheet"
worksheet := jslink newCommandFactory
	<< 'const excel = require(''excel4node'')';
	<< 'let workbook = new excel.Workbook()';
	<< 'let worksheet = workbook.addWorksheet(''HW'')';
	<< 'worksheet';
	sendAndWait.

"Write Hello, World!"
worksheet newCommandFactory
	<< 'this.cell(2, 2).string("Hello, World!")';
	sendAndWait.

"Save the spreadsheet"
worksheet newCommandFactory
	<< 'this.wb.write("hw.xlsx")';
	sendAndWait.

"Stop the server"
jslink stop

Second, using JavaScript generated with JavaScriptGenerator:

"Start JSLink"
jslink := JSLinkApplication withDefaultSettings.
jslink start.

"Ensure that the 'excel4node' module is installed."
jslink installModule: 'excel4node'

"Create the spreadsheet and worksheet"
excel := #excel asJSGIdentifier.
wb := #wb asJSGIdentifier.
ws := #ws asJSGIdentifier.
worksheet := jslink newCommandFactory
	<< (excel <- #'excel4node' require) beLetDeclaration;
	<< (wb <- (excel => #Workbook) call new) beLetDeclaration;
	<< (ws <- ((wb => #addWorksheet) callWith: { 'HW' })) beLetDeclaration;
	<< 'ws';
	sendAndWait.

"Write Hello, World!"
worksheet newCommandFactory
	<< (((#this asJSGI => #cell callWith: { 2. 2. }) => #string) callWith: { 'Hello, World!'});
	sendAndWait.

"Save the spreadsheet"
worksheet newCommandFactory
	<< ((#this asJSGI => #wb => #write) callWith: { 'hw2.xlsx' });
	sendAndWait.

"Stop the server"
jslink stop

Proxy objects register them selves for finalisation. When they are garbage collected in Pharo they are automatically removed from the registry in the node.js server.

Callbacks in to Pharo from node.js are supported through observables.

See JSLinkSendCommandTest for examples of setting up and using callbacks.

See the 'JSLink-Tests` package.

PythonBridge supports communicating with the server using either HTTP or MsgPack. While the code has been left in the package, MsgPack is not yet supported.

Currently JSLink is specific to node.js. Planned future work includes adding support for the debug port in node.js, to provide better program control, and adding support for browsers, initially Chrome, using their debug port.

Thanks to the team at ObjectProfile for making PythonBridge, on which JSLink is based, and to Julien Delplanque for Python3Generator, on which JavaScriptGenerator is based.