Package-level declarations

Types

Link copied to clipboard
class BindScope<T : Any>

What bind gives you: a place to name the members a script should see.

Link copied to clipboard

How loud a console message is.

Link copied to clipboard
data class ConsoleMessage(val level: ConsoleLevel, val text: String)

One console message, already formatted.

Link copied to clipboard
fun interface ConsolePrinter

Where console.log and its neighbours end up. Every engine formats the arguments the same way before they get here: separated by spaces, with %s, %d, %i, %f, %o, %O and %c in a leading string filled in, as a browser console does.

Link copied to clipboard

Printers you probably want.

Link copied to clipboard
object Converters

The fixed table between Kotlin values and JavaScript values. Nothing here uses reflection, so it works the same on every target and for every engine.

Link copied to clipboard
@RequiresOptIn(level = RequiresOptIn.Level.ERROR, message = "This is for engine implementations. Application code builds a KiteJs from an engine and uses the values and handles it gives out.")
annotation class InternalKiteJsApi

Marks the parts of this API that exist for the engines implementing it, not for the code that embeds an engine. An application builds a KiteJs from an engine and works with the handles it gives out; it never needs these.

Link copied to clipboard
abstract class JsArray : JsObject

A JavaScript array seen from Kotlin.

Link copied to clipboard
interface JsEngine<C : KiteJsConfig>

A JavaScript engine a KiteJs can run on. Each engine module has one, an object you pass to KiteJs: Rhino from kitejs-rhino, QuickJs from kitejs-quickjs. C is the engine's own configuration, which has everything KiteJsConfig has plus what only that engine can do.

Link copied to clipboard
class JsEngineError(message: String, cause: Throwable? = null) : JsException

The engine itself could not go on: it is closed, misused, out of budget or out of memory.

Link copied to clipboard
class JsError(val value: JsValue, val name: String, message: String, val scriptStack: List<JsStackFrame>, cause: Throwable?) : JsException

A script threw. value is whatever it threw, which is usually an Error but need not be.

Link copied to clipboard

Anything the API throws. Every case is one of the three below.

Link copied to clipboard
abstract class JsFunction : JsObject

A JavaScript function seen from Kotlin.

Link copied to clipboard
abstract class JsObject

A JavaScript object seen from Kotlin. Reading and writing goes straight through to the engine, so a change here is a change the script sees.

Link copied to clipboard
class JsPromiseHandle(val promise: JsObject, resolveFn: JsFunction, rejectFn: JsFunction)

A promise the host controls: hand promise to the script, settle it when you are ready.

Link copied to clipboard
abstract class JsScript

A parsed script, ready to run more than once.

Link copied to clipboard
data class JsStackFrame(val functionName: String?, val fileName: String?, val lineNumber: Int)

One frame of a script's own call stack.

Link copied to clipboard
abstract class JsSymbol

A JavaScript symbol. It is a primitive, but its identity belongs to the engine that made it, so it cannot be handed to another engine.

Link copied to clipboard
class JsSyntaxError(message: String, val fileName: String?, val lineNumber: Int, val columnNumber: Int, val lineSource: String?, cause: Throwable?) : JsException

The source did not parse.

Link copied to clipboard
enum class JsType : Enum<JsType>

What a JsValue holds. A when over this covers every JavaScript value, so the compiler can tell you when you have missed one.

Link copied to clipboard

The undefined a JsValue holds. Engines compare against it when they turn a value into their own; nothing else needs it, since JsValue.isUndefined answers the question.

Link copied to clipboard
value class JsValue(val raw: Any?)

One value from an engine. It costs nothing at runtime: the wrapper disappears and only the value itself is passed around.

Link copied to clipboard

An arbitrary-precision integer: what BigInt values are made of.

Link copied to clipboard
abstract class KiteJs : AutoCloseable

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.

Link copied to clipboard
open class KiteJsConfig

How to build an engine: what every engine understands. Everything has a working default, and an engine's own configuration adds what only it can do.

Link copied to clipboard

Which primitive an object is asked for, as the ECMAScript ToPrimitive hint.

Link copied to clipboard
class PropertyFlags(val writable: Boolean = true, val enumerable: Boolean = true, val configurable: Boolean = true)

How a property behaves. The defaults match what obj.x = 1 gives you in a script.

Properties

Link copied to clipboard

True when this value is thenable, which is what await looks for: an object, an array or a function whose then is callable. Reading then can run a getter, so for those this needs the value's engine open and on this thread, and a getter that throws reaches you as a JsError. Every other value answers false without touching an engine.

Functions

Link copied to clipboard
fun JsObject.accessor(name: String, flags: PropertyFlags = PropertyFlags(), read: () -> Any?, write: (JsValue) -> Unit)

A property with both halves.

Link copied to clipboard
fun <T : Any> JsObject.bind(name: String, instance: T, build: BindScope<T>.() -> Unit): JsObject

Binds a Kotlin object into a fresh JavaScript object.

Link copied to clipboard
fun JsObject.constant(name: String, value: Any?)

Puts a value that a script can read but not change.

Link copied to clipboard
fun JsObject.constructor(name: String, arity: Int = 0, flags: PropertyFlags = PropertyFlags(enumerable = false), build: (JsObject, List<JsValue>) -> Unit): JsFunction

A host constructor, callable with new. build fills in the object it is given.

Link copied to clipboard
inline fun <reified T> JsValue.convertTo(): T

Reads a JsValue as T, coercing the way JavaScript would where that makes sense.

Link copied to clipboard
inline fun <reified A, reified R> JsObject.function(name: String, crossinline body: (A) -> R): JsFunction

A one-argument host function, with the argument and the answer converted for you.

inline fun <reified A, reified B, reified R> JsObject.function(name: String, crossinline body: (A, B) -> R): JsFunction

A two-argument host function.

inline fun <reified A, reified B, reified C, reified R> JsObject.function(name: String, crossinline body: (A, B, C) -> R): JsFunction

A three-argument host function.

fun JsObject.function(name: String, arity: Int = 0, flags: PropertyFlags = PropertyFlags(enumerable = false), body: (List<JsValue>) -> Any?): JsFunction

A host function that takes the arguments as they came.

Link copied to clipboard
fun JsObject.getter(name: String, flags: PropertyFlags = PropertyFlags(), read: () -> Any?)

A property computed on every read.

Link copied to clipboard
fun <C : KiteJsConfig> KiteJs(engine: JsEngine<C>, configure: C.() -> Unit = {}): KiteJs

Builds an engine on engine, on this thread. See KiteJsConfig for what every engine takes and the engine's own configuration for the rest.

Link copied to clipboard
fun JsObject.method(name: String, arity: Int = 0, flags: PropertyFlags = PropertyFlags(enumerable = false), body: (self: JsValue, args: List<JsValue>) -> Any?): JsFunction

A host function that also wants the this it was called on.

Link copied to clipboard

A promise the host settles later.

Link copied to clipboard
fun JsObject.obj(name: String, build: JsObject.() -> Unit = {}): JsObject

A nested object, built by build. Returns it so you can keep a handle.

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
fun JsObject.property(name: String, value: Any?, flags: PropertyFlags = PropertyFlags())

Puts a value on the object.

Link copied to clipboard
fun JsObject.setter(name: String, flags: PropertyFlags = PropertyFlags(), write: (JsValue) -> Unit)

A property that only accepts writes.