Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make it easier to understand the type mapping between KT and JS #3801

Merged
merged 6 commits into from
Nov 17, 2023
Merged

Make it easier to understand the type mapping between KT and JS #3801

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0d2b897
docs: make it easier to understand the type mapping between KT and JS
lppedd Sep 23, 2023
1e13055
docs: minor cleanup
lppedd Sep 23, 2023
78acd81
Merge branch 'master' into docs/kt-js-mapping
koshachy Oct 25, 2023
cce0763
Merge branch 'master' into docs/kt-js-mapping
koshachy Nov 9, 2023
e32cdc0
chore: update js-to-kotlin-interop.md
koshachy Nov 17, 2023
695c1cb
Merge branch 'master' into docs/kt-js-mapping
koshachy Nov 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 28 additions & 20 deletions docs/topics/js/js-to-kotlin-interop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,9 +120,34 @@ the JavaScript target, and allows you to also export Kotlin declarations that ar

## Kotlin types in JavaScript

* Kotlin numeric types, except for `kotlin.Long` are mapped to JavaScript `Number`.
* `kotlin.Char` is mapped to JavaScript `Number` representing character code.
* Kotlin can't distinguish between numeric types at run time (except for `kotlin.Long`), so the following code works:
See how Kotlin types are mapped to JavaScript ones:

| Kotlin | JavaScript | Comments |
|-----------------------------------------------------------------------------|-----------------------------|--------------------------------------------------------------------------------------------|
| `Byte`, `Short`, `Int`, `Float`, `Double` | `Number` | |
| `Char` | `Number` | The number represents the character's code. |
| `Long` | Not supported | There is no 64-bit integer number type in JavaScript, so it is emulated by a Kotlin class. |
| `Boolean` | `Boolean` | |
| `String` | `String` | |
| `Array` | `Array` | |
| `ByteArray` | `Int8Array` | |
| `ShortArray` | `Int16Array` | |
| `IntArray` | `Int32Array` | |
| `CharArray` | `UInt16Array` | Carries the property `$type$ == "CharArray"`. |
| `FloatArray` | `Float32Array` | |
| `DoubleArray` | `Float64Array` | |
| `LongArray` | `Array<kotlin.Long>` | Carries the property `$type$ == "LongArray"`. Also see Kotlin's Long type comment. |
| `BooleanArray` | `Int8Array` | Carries the property `$type$ == "BooleanArray"`. |
| `Unit` | Undefined | |
| `Any` | `Object` | |
| `Throwable` | `Error` | |
| Nullable `Type?` | `Type \| null \| undefined` | |
| All other Kotlin types (except for those marked with `JsExport` annotation) | Not supported | Includes Kotlin's collections (`List`, `Set`, `Map`, etc.), and unsigned variants. |

Additionaly, it is important to know that:

* Kotlin preserves overflow semantics for `kotlin.Int`, `kotlin.Byte`, `kotlin.Short`, `kotlin.Char` and `kotlin.Long`.
* Kotlin cannot distinguish between numeric types at runtime (except for `kotlin.Long`), so the following code works:

```kotlin
fun f() {
Expand All @@ -132,22 +157,5 @@ the JavaScript target, and allows you to also export Kotlin declarations that ar
}
```

* Kotlin preserves overflow semantics for `kotlin.Int`, `kotlin.Byte`, `kotlin.Short`, `kotlin.Char` and `kotlin.Long`.
* `kotlin.Long` is not mapped to any JavaScript object, as there is no 64-bit integer number type in JavaScript. It is emulated by a Kotlin class.
* `kotlin.String` is mapped to JavaScript `String`.
* `kotlin.Any` is mapped to JavaScript `Object` (`new Object()`, `{}`, and so on).
* `kotlin.Array` is mapped to JavaScript `Array`.
* Kotlin collections (`List`, `Set`, `Map`, and so on) are not mapped to any specific JavaScript type.
* `kotlin.Throwable` is mapped to JavaScript Error.
* Kotlin preserves lazy object initialization in JavaScript.
* Kotlin does not implement lazy initialization of top-level properties in JavaScript.

### Primitive arrays

Primitive array translation utilizes JavaScript `TypedArray`:

* `kotlin.ByteArray`, `-.ShortArray`, `-.IntArray`, `-.FloatArray`, and `-.DoubleArray` are mapped to
JavaScript `Int8Array`, `Int16Array`, `Int32Array`, `Float32Array`, and `Float64Array` correspondingly.
* `kotlin.BooleanArray` is mapped to JavaScript `Int8Array` with a property `$type$ == "BooleanArray"`.
* `kotlin.CharArray` is mapped to JavaScript `UInt16Array` with a property `$type$ == "CharArray"`.
* `kotlin.LongArray` is mapped to JavaScript `Array` of `kotlin.Long` with a property `$type$ == "LongArray"`.