KiteJs

abstract class KiteJs : AutoCloseable(source)

An engine and the global scope that goes with it. One instance belongs to the thread that opened it: use it and close it there.

KiteJs(Rhino).use { js ->
js.global.function("shout") { args -> args.first().asString().uppercase() }
println(js.evaluate("shout('hi')").asString()) // HI
}

Every outermost call from the host into the engine, evaluate, running a JsScript, calling a JsFunction or a method, runs the Promise reactions it queued before it returns. Work queued later, from a host callback, waits for the next such call or for runMicrotasks.

An exception a host function throws is not a JavaScript exception: no catch in the script sees it, and it comes out of the call that started the script as itself when it is a JsException, or inside a JsEngineError otherwise.

Constructors

Link copied to clipboard
constructor()

Properties

Link copied to clipboard
open val canPause: Boolean

Whether evaluatePausing really pauses here. Only QuickJS on a browser or Node with WebAssembly stack switching (JSPI) can; everywhere else it runs like evaluate.

Link copied to clipboard
abstract val engine: JsEngine<*>

The engine underneath, such as Rhino or QuickJs.

Link copied to clipboard
abstract val global: JsObject

The global object. Bind host functions and values onto it.

Link copied to clipboard
abstract val version: String

The engine's name and version.

Functions

Link copied to clipboard
abstract override fun close()

Releases the engine. Using it afterwards throws, and so does every handle it gave out. Only the thread that opened it can release it; from another thread this throws and leaves the engine open. Closing it again does nothing.

Link copied to clipboard
abstract fun compile(source: String, fileName: String = "<script>"): JsScript

Parses source once so it can be run many times.

Link copied to clipboard
abstract fun evaluate(source: String, fileName: String = "<eval>"): JsValue

Parses and runs source. The answer is the last expression's value.

Link copied to clipboard
open suspend fun evaluatePausing(source: String, fileName: String = "<eval>", slice: Duration = 16.milliseconds): JsValue

Runs source like evaluate, but where canPause is true the script pauses about every slice and lets the event loop run before it goes on. A long script then does not freeze the page on a platform with one thread.

Link copied to clipboard
open fun loadBytecode(bytecode: ByteArray): JsScript

A script from bytecode that JsScript.bytecode wrote in an engine of the same kind and version, ready to run here without a parse. The engine runs bytecode without checking it, so load only bytecode the host wrote itself, never bytes from a document or the network. Throws a JsEngineError on an engine that has no bytecode, and for bytes it cannot read.

Link copied to clipboard
abstract fun newArray(vararg elements: Any?): JsArray

A fresh array holding elements.

Link copied to clipboard
abstract fun newConstructor(name: String, arity: Int, build: (JsObject, List<JsValue>) -> Unit): JsFunction

A host constructor: new makes a plain object and hands it to build to fill in.

Link copied to clipboard
abstract fun newFunction(name: String, arity: Int, body: (self: JsValue, args: List<JsValue>) -> Any?): JsFunction

A host function named name. body gets this and the arguments, and its answer goes back through Converters.

Link copied to clipboard
abstract fun newObject(): JsObject

A fresh empty object, the same as {} in a script.

Link copied to clipboard

A promise the host settles later.

Link copied to clipboard
fun KiteJs.onSettled(value: JsValue, onSettled: (JsValue, JsValue?) -> Unit): Boolean

Registers onSettled on value the way await value attaches to it. It is called once, with the value and a null error on success, or with undefined and the reason on failure.

Link copied to clipboard
abstract fun runMicrotasks()

Runs whatever the promise callbacks have queued. Evaluating already drains the queue at the end of the call, so this is only for work queued from a host callback afterwards.

Link copied to clipboard
abstract fun thenableCheck(obj: JsObject): Boolean

Whether obj has a callable then, read once, as a host call.

Link copied to clipboard
abstract fun valueOf(value: Any?): JsValue

A Kotlin value as the engine sees it, collections and all. See Converters.

Link copied to clipboard
abstract fun watchSettlement(value: JsValue, onSettled: (JsValue, JsValue?) -> Unit): Boolean

What onSettled does; see there.