From cc1c7ef44372992f1198dd17f2b7305cb78107fb Mon Sep 17 00:00:00 2001
From: alepedroza <39709865+AlejandraPedroza@users.noreply.github.com>
Date: Thu, 20 Nov 2025 12:04:12 -0600
Subject: [PATCH] Use of `BigInt64Array` type
---
docs/topics/js/js-to-kotlin-interop.md | 72 +++++++++++++++++---------
1 file changed, 48 insertions(+), 24 deletions(-)
diff --git a/docs/topics/js/js-to-kotlin-interop.md b/docs/topics/js/js-to-kotlin-interop.md
index a39d515c2ab..f042acb37ff 100644
--- a/docs/topics/js/js-to-kotlin-interop.md
+++ b/docs/topics/js/js-to-kotlin-interop.md
@@ -213,35 +213,59 @@ kotlin {
2. Enable the `BigInt` type. See how to enable it in [Use of `BigInt` type to represent Kotlin's `Long` type](#use-bigint-type-to-represent-kotlin-s-long-type).
+### Use `BigInt64Array` type to represent Kotlin's `LongArray` type
+
+
+Kotlin/JS uses JavaScript's built-in `BigInt64Array` type
+to represent Kotlin's `LongArray` values when compiling to JavaScript.
+
+To enable support for the `BigInt64Array` type, you need to add the following compiler option to your
+`build.gradle(.kts)` file:
+
+```kotlin
+// build.gradle.kts
+kotlin {
+ js {
+ ...
+ compilerOptions {
+ freeCompilerArgs.add("-Xes-long-as-bigint")
+ }
+ }
+}
+```
+
+This feature is [Experimental](components-stability.md#stability-levels-explained). Share your feedback in our issue tracker,
+[YouTrack](https://youtrack.jetbrains.com/issue/KT-79284/Use-BigInt64Array-for-LongArray).
+
## Kotlin types in JavaScript
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. |
+| Kotlin | JavaScript | Comments |
+|------------------------------------------------------------------|---------------------------|---------------------------------------------------------------------------------------------------------|
+| `Byte`, `Short`, `Int`, `Float`, `Double` | `Number` | |
+| `Char` | `Number` | The number represents the character's code. |
| `Long` | `BigInt` | Needs the [`-Xes-long-as-bigint` compiler option](compiler-reference.md#xes-long-as-bigint) configured. |
-| `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` | Carries the property `$type$ == "LongArray"`. Also see Kotlin's Long type comment. |
-| `BooleanArray` | `Int8Array` | Carries the property `$type$ == "BooleanArray"`. |
-| `List`, `MutableList` | `KtList`, `KtMutableList` | Exposes an `Array` via `KtList.asJsReadonlyArrayView` or `KtMutableList.asJsArrayView`. |
-| `Map`, `MutableMap` | `KtMap`, `KtMutableMap` | Exposes an ES2015 `Map` via `KtMap.asJsReadonlyMapView` or `KtMutableMap.asJsMapView`. |
-| `Set`, `MutableSet` | `KtSet`, `KtMutableSet` | Exposes an ES2015 `Set` via `KtSet.asJsReadonlySetView` or `KtMutableSet.asJsSetView`. |
-| `Unit` | Undefined | Exportable when used as return type, but not when used as parameter type. |
-| `Any` | `Object` | |
-| `Throwable` | `Error` | |
-| `enum class Type` | `Type` | Enum entries are exposed as static class properties (`Type.ENTRY`). |
-| Nullable `Type?` | `Type | null | undefined` | |
-| All other Kotlin types, except for those marked with `@JsExport` | Not supported | Includes Kotlin's [unsigned integer types](unsigned-integer-types.md). |
+| `Boolean` | `Boolean` | |
+| `String` | `String` | |
+| `Array` | `Array` | |
+| `ByteArray` | `Int8Array` | |
+| `ShortArray` | `Int16Array` | |
+| `IntArray` | `Int32Array` | |
+| `CharArray` | `UInt16Array` | Carries the property `$type$ == "CharArray"`. |
+| `FloatArray` | `Float32Array` | |
+| `DoubleArray` | `Float64Array` | |
+| `LongArray` | `BigInt64Array` | |
+| `BooleanArray` | `Int8Array` | Carries the property `$type$ == "BooleanArray"`. |
+| `List`, `MutableList` | `KtList`, `KtMutableList` | Exposes an `Array` via `KtList.asJsReadonlyArrayView` or `KtMutableList.asJsArrayView`. |
+| `Map`, `MutableMap` | `KtMap`, `KtMutableMap` | Exposes an ES2015 `Map` via `KtMap.asJsReadonlyMapView` or `KtMutableMap.asJsMapView`. |
+| `Set`, `MutableSet` | `KtSet`, `KtMutableSet` | Exposes an ES2015 `Set` via `KtSet.asJsReadonlySetView` or `KtMutableSet.asJsSetView`. |
+| `Unit` | Undefined | Exportable when used as return type, but not when used as parameter type. |
+| `Any` | `Object` | |
+| `Throwable` | `Error` | |
+| `enum class Type` | `Type` | Enum entries are exposed as static class properties (`Type.ENTRY`). |
+| Nullable `Type?` | `Type | null | undefined` | |
+| All other Kotlin types, except for those marked with `@JsExport` | Not supported | Includes Kotlin's [unsigned integer types](unsigned-integer-types.md). |
Additionally, it is important to know that: