Qore v8 Module

Table of Contents

• v8 Module Introduction
• Examples
• JavaScript to Qore Data Conversions
• Qore to JavaScript Data Conversions
• JavaScript Exceptions
• Managing References to Qore Data in JavaScript
  • Default Qore Reference Management
  • Explicit Qore Reference Management
• v8 Module Release Notes
  • v8 Module Version 1.0

v8 Module Introduction

The v8 module allows for the execution and management of JavaScript code in Qore.

To use the module in a Qore script, use the %requires directive as follows:

%requires v8 

Note that while JavaScript and v8 support threading, calls into a single JavaScriptProgram are subject to thread serialization; only one thread can be active

Also included with the v8 module:

• TypeScriptActionInterface an API for allowing data provider app actions to be created from TypeScript / JavaScript

Main classes:

• JavaScriptProgram
• JavaScriptObject

Examples

Example:

#!/usr/bin/env qore
 
%new-style
%require-types
%strict-args
%enable-all-warnings
 
%requires v8
 
JavaScriptProgram js("var foo = function(arg) { return arg + 1; }", "test.js");
js.run();
JavaScriptObject gb = js.getGlobal();
JavaScriptObject foo = gb.getKeyValue("foo");
int i = foo.callAsFunction(gb, 1);

JavaScript to Qore Data Conversions

Source JavaScript Type	Target Qore Type
bool	bool
int32, uint32, bigint	int or number if greater than 64-bits
number	float
array	list
string	string
object	V8::JavaScriptObject
null, undefined	NOTHING

Other JavaScript types cannot be converted to Qore; attempting to convert an unsupported type will result in a runtime exception.

Qore to JavaScript Data Conversions

Source Qore Type	Target JavaScript Type
binary	string (base64-encoded value)
bool	bool
date	string (ISO-8601 format)
float	number
hash	object
int	int32, uint32, bigint
list	array
string	string
V8::JavaScriptObject	object
code	callable object
NOTHING, NULL	null

Other Qore types cannot be converted to JavaScript; attempting to convert an unsupported type will result in a runtime exception.

JavaScript Exceptions

Exceptions in JavaScript are propagated to Qore as Qore exceptions.

Managing References to Qore Data in JavaScript

Qore's deterministic garbage collection approach and reliance on destructors means that references to Qore data stored in JavaScript must have their reference counts managed externally.

JavaScript objects storing references to Qore data hold only weak references to Qore data.

Default Qore Reference Management

By default, Qore references are saved in thread-local data, so the lifecycle of the object is automatically limited to the existence of the thread.

The thread-local hash key name used to save the list of objects created is determined by the value of the "_v8_save" thread-local key, if set. If no such key is set, then "_v8_save" is used instead as the literal key for saving the list of objects.

Explicit Qore Reference Management

References to Qore data can be managed explicitly by using the JavaScriptProgram::setSaveReferenceCallback() method to set a callback that is called every time a Qore references is stored in a JavaScript object.

This callback must take a single auto argument as in the following example:

hash<auto> ref_cache;
code callback = sub (auto v) {
    # save reference in cache, so it doesn't go out of scope
    ref_cache{v.uniqueHash()} = v;
}
JavaScriptProgram::setSaveReferenceCallback(callback);

v8 Module Release Notes

v8 Module Version 1.0

• initial public release