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.

Kotlin to JavaScript: null and Unit become undefined, Boolean stays, every number widens to a JavaScript number, a Long outside the range a JavaScript number holds exactly becomes a BigInt, a Char or any CharSequence becomes a string, a ByteArray becomes a Uint8Array over a copy of its bytes, and List, Array, the other primitive arrays and Set become arrays and Map a plain object, all the way down. Cycles and repeated collection references keep their identity within one conversion; another conversion makes a separate copy. A JsValue or a handle passes straight through. Anything else goes to the converters register added, and is refused when none of them takes it.

JavaScript to Kotlin, as JsValue.toKotlin does it: undefined and null become null, numbers Double, strings String, booleans Boolean, BigInts KBigInt, arrays List, an ArrayBuffer, a typed array or a DataView a ByteArray of the bytes it views, and other objects Map, all the way down. A function stays a JsFunction and a symbol a JsSymbol.

Functions

Link copied to clipboard
fun canonical(value: Any?): Any?

value with every scalar in its canonical form, the form a JsValue holds. A collection comes back as it was, for toEngine to walk. A value no rule takes is refused.

Link copied to clipboard

Forgets every rule register added.

Link copied to clipboard
fun isCollection(value: Any?): Boolean

Whether canonical left value as a collection for toEngine to walk.

Link copied to clipboard
fun register(convert: (Any) -> Any?)

Teaches the table one more Kotlin type. convert answers anything the table already understands, a Map for instance, or null to let the next rule try. The first rule that answers wins. Rules apply to every engine. A chain that cycles or takes more than 256 transformations before reaching the built-in table throws JsEngineError.

Link copied to clipboard
fun <V> toEngine(value: Any?, scalar: (Any?) -> V, array: (List<V>) -> V, obj: (List<Pair<String, V>>) -> V, bytes: (ByteArray) -> V): V

Builds value in an engine: scalar takes a canonical scalar or a handle and answers the engine's own value, array builds an array from elements already built, obj a plain object from keys and values already built, and bytes a Uint8Array over a copy of bytes. These callbacks cannot build cycles; cyclic input or a depth of 128 throws JsEngineError. Engines use toEngineGraph to preserve graphs without a traversal depth limit.

Link copied to clipboard
fun <V> toEngineGraph(value: Any?, scalar: (Any?) -> V, array: () -> V, obj: () -> V, append: (V, V) -> Unit, put: (V, String, V) -> Unit, bytes: (ByteArray) -> V): V

Builds a graph without recursive host calls. array and obj allocate empty destinations; append and put fill them without consuming the child values. Collections and custom objects converted to collections retain their identity within this call. The caller owns the engine values the callbacks allocate and must clean up temporaries, including on error.