JavaScript Use in CSPro

Overview

Most CSPro application developers will exclusively use the CSPro programming language when adding logic to applications, but it is also possible to use JavaScript, a popular programming language that is frequently used in web development. Unlike CSPro logic, JavaScript is dynamically typed, meaning that the type of variables is not known at compile-time. An abundance of material exists on the Internet describing JavaScript and explaining the language's syntax, so these helps are a high-level overview intended for users who know JavaScript and want to incorporate it in a CSPro application.

Using the JS namespace, it is possible to evaluate JavaScript, invoke functions, and convert CSPro symbols to JavaScript numbers, strings, arrays, and objects. It is also possible to create function wrappers in CSPro logic that appear as user-defined functions but call into JavaScript when invoked.

In addition to including JavaScript as part of a CSPro application, it is also possible to execute JavaScript from within CSCode.

JavaScript Engine

CSPro uses the QuickJS-NG JavaScript Engine, a "small and embeddable JavaScript engine....that supports the ES2023 specification including modules, asynchronous generators, proxies and BigInt."

CSPro executes JavaScript in the same thread as CSPro logic, so a call from CSPro logic into JavaScript will pause termination of the CSPro logic until the script, and any promises, are fully evaluated.

JavaScript Context

JavaScript is evaluated using a single shared global execution context. This means that any objects introduced into the global object are available to all scripts.

When CSPro displays HTML in a web view, the web browser that displays the HTML also supports JavaScript evaluation. The browser's JavaScript is separate from that run by QuickJS-NG and does not share the global execution contet. You can use the Action Invoker to transfer data between QuickJS-NG's context and the web browser's JavaScript context.

JavaScript Execution Using Files

You can associate JavaScript files with an application by selecting File -> Manage Application Files. By modifying the properties for the code file, you can indicate how the JavaScript should be evaluated:

JavaScript (Global): The file will be evaluated as a JavaScript global script.
JavaScript (ECMAScript Module): The file will be evaluated as a JavaScript module.

When a CSPro application starts, any JavaScript associated with the application is evaluated. If the evaluation results in an exception, the application will terminate. If there are any module loading errors, the application will also terminate, though this behavior can be modified.

After a successful application start, the Action Invoker is available for use in the JavaScript environment using the name CS. Use of the Action Invoker can be disabled, or you can change the name of the object. The Action Invoker is not available during the application startup, so any use of the Action Invoker cannot occur in the global context but must instead occur in functions.

JavaScript Execution Using Logic

While JavaScript files are evaluated at application startup, you will need to use logic to call into JavaScript from within your application. The JS namespace contains functions that facilitate such interactions with the following functions:

Function	Description
JS.eval	Evaluates JavaScript in the global execution context.
JS.getValue	Converts a JavaScript variable or property to its CSPro equivalent.
JS.getValueJson	Returns the JSON representation of a JavaScript variable or property.
JS.hasValue	Returns whether a JavaScript variable or property is defined (not undefined).
JS.invoke	Executes a JavaScript function that exists in the global execution context with any CSPro arguments converted to their JavaScript equivalents.
JS.setValue	Converts a CSPro variable to its JavaScript equivalent and adds this as a variable to the global scope, or sets an object's property.
JS.setValueFromJson	Create a JavaScript variable using JSON and adds it as a variable to the global scope, or sets an object's property.

When executing JavaScript from CSPro logic, any uncaught exceptions will be displayed as error messages.

JavaScript Logging

Both the print and console.log functions write to the application's listing file.