From 78dbbaafdd4a732f6cbb1525816b38a51adcf1cf Mon Sep 17 00:00:00 2001 From: HyunWoo Lee Date: Fri, 2 May 2025 11:02:52 -0700 Subject: [PATCH] Support collections dsl (#51042) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Summary: This PR introduces a concise Kotlin DSL for constructing `ReadableMap` and `ReadableArray` in Android native modules: - Adds `buildReadableMap { … }` and `buildReadableArray { … }` functions, modeled after Kotlin’s `buildMap`/`buildList` APIs. - Wraps `Arguments.createMap()` / `Arguments.createArray()` in a type-safe, nested DSL to reduce boilerplate and prevent errors. - Improves readability and maintainability when assembling nested map/array structures for React Native bridges. Current code like: ```kotlin val map = Arguments.createMap().apply { putString("name", user.name) putInt("age", user.age) // … } ``` can now be written as: ```kotlin val userMap = buildReadableMap { put("name", user.name) put("age", user.age) put("scores") { user.scores.forEach { add(it) } } } ``` This feature proposal also written in [[Android] Support Collection DSL](https://github.com/react-native-community/discussions-and-proposals/issues/899) ## Changelog: [Android] [Added] - Collections DSL functions for Kotlin(`buildReadableMap`, `buildReadableArray`) Pull Request resolved: https://github.com/facebook/react-native/pull/51042 Test Plan: ### Run Unit Test ```shell cd packages/react-native/ReactAndroid ./gradlew :ReactAndroid:unitTest ``` Ensure all tests in `src/test/java/.../ReadableMapBuilderTest.kt` and `ReadableArrayBuilderTest.kt` pass. Reviewed By: javache Differential Revision: D73986390 Pulled By: cortinico fbshipit-source-id: b9f94327646bcb6e0190cdd06dfb9bb5eaa6375c --- .../ReactAndroid/api/ReactAndroid.api | 32 +++++++ .../react/bridge/ReadableArrayBuilder.kt | 61 +++++++++++++ .../react/bridge/ReadableMapBuilder.kt | 61 +++++++++++++ .../react/bridge/ReadableArrayBuilderTest.kt | 70 +++++++++++++++ .../react/bridge/ReadableMapBuilderTest.kt | 86 +++++++++++++++++++ .../testutils/shadows/ShadowNativeArray.kt | 10 +-- .../testutils/shadows/ShadowNativeMap.kt | 4 +- 7 files changed, 317 insertions(+), 7 deletions(-) create mode 100644 packages/react-native/ReactAndroid/src/main/java/com/facebook/react/bridge/ReadableArrayBuilder.kt create mode 100644 packages/react-native/ReactAndroid/src/main/java/com/facebook/react/bridge/ReadableMapBuilder.kt create mode 100644 packages/react-native/ReactAndroid/src/test/java/com/facebook/react/bridge/ReadableArrayBuilderTest.kt create mode 100644 packages/react-native/ReactAndroid/src/test/java/com/facebook/react/bridge/ReadableMapBuilderTest.kt diff --git a/packages/react-native/ReactAndroid/api/ReactAndroid.api b/packages/react-native/ReactAndroid/api/ReactAndroid.api index 7eea38b4872..e76abf9a4a1 100644 --- a/packages/react-native/ReactAndroid/api/ReactAndroid.api +++ b/packages/react-native/ReactAndroid/api/ReactAndroid.api @@ -1353,6 +1353,22 @@ public abstract interface class com/facebook/react/bridge/ReadableArray { public abstract fun toArrayList ()Ljava/util/ArrayList; } +public final class com/facebook/react/bridge/ReadableArrayBuilder { + public fun (Lcom/facebook/react/bridge/WritableArray;)V + public final fun add (D)V + public final fun add (I)V + public final fun add (J)V + public final fun add (Ljava/lang/String;)V + public final fun add (Z)V + public final fun addArray (Lkotlin/jvm/functions/Function1;)V + public final fun addMap (Lkotlin/jvm/functions/Function1;)V + public final fun addNull ()V +} + +public final class com/facebook/react/bridge/ReadableArrayBuilderKt { + public static final fun buildReadableArray (Lkotlin/jvm/functions/Function1;)Lcom/facebook/react/bridge/ReadableArray; +} + public abstract interface class com/facebook/react/bridge/ReadableMap { public abstract fun getArray (Ljava/lang/String;)Lcom/facebook/react/bridge/ReadableArray; public abstract fun getBoolean (Ljava/lang/String;)Z @@ -1370,6 +1386,22 @@ public abstract interface class com/facebook/react/bridge/ReadableMap { public abstract fun toHashMap ()Ljava/util/HashMap; } +public final class com/facebook/react/bridge/ReadableMapBuilder { + public fun (Lcom/facebook/react/bridge/WritableMap;)V + public final fun put (Ljava/lang/String;D)V + public final fun put (Ljava/lang/String;I)V + public final fun put (Ljava/lang/String;J)V + public final fun put (Ljava/lang/String;Ljava/lang/String;)V + public final fun put (Ljava/lang/String;Z)V + public final fun putArray (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V + public final fun putMap (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V + public final fun putNull (Ljava/lang/String;)V +} + +public final class com/facebook/react/bridge/ReadableMapBuilderKt { + public static final fun buildReadableMap (Lkotlin/jvm/functions/Function1;)Lcom/facebook/react/bridge/ReadableMap; +} + public abstract interface class com/facebook/react/bridge/ReadableMapKeySetIterator { public abstract fun hasNextKey ()Z public abstract fun nextKey ()Ljava/lang/String; diff --git a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/bridge/ReadableArrayBuilder.kt b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/bridge/ReadableArrayBuilder.kt new file mode 100644 index 00000000000..cf125b747c2 --- /dev/null +++ b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/bridge/ReadableArrayBuilder.kt @@ -0,0 +1,61 @@ +/* + * Copyright (c) Meta Platforms, Inc. and affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +package com.facebook.react.bridge + +/** + * Convenience class for building a [ReadableArray] in a Kotlin idiomatic way. You can use it as + * follows: + * ``` + * val array: ReadableArray = buildReadableArray { + * add("one") + * add(2) + * add(true) + * addNull() + * addMap { put("nestedKey", "nestedValue") } + * } + * ``` + */ +public inline fun buildReadableArray(builder: ReadableArrayBuilder.() -> Unit): ReadableArray { + val array: WritableArray = Arguments.createArray() + ReadableArrayBuilder(array).apply(builder) + return array +} + +public class ReadableArrayBuilder(private val array: WritableArray) { + public fun add(value: String?) { + array.pushString(value) + } + + public fun add(value: Int) { + array.pushInt(value) + } + + public fun add(value: Boolean) { + array.pushBoolean(value) + } + + public fun add(value: Double) { + array.pushDouble(value) + } + + public fun add(value: Long) { + array.pushDouble(value.toDouble()) + } + + public fun addNull() { + array.pushNull() + } + + public fun addMap(builder: ReadableMapBuilder.() -> Unit) { + array.pushMap(buildReadableMap(builder)) + } + + public fun addArray(builder: ReadableArrayBuilder.() -> Unit) { + array.pushArray(buildReadableArray(builder)) + } +} diff --git a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/bridge/ReadableMapBuilder.kt b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/bridge/ReadableMapBuilder.kt new file mode 100644 index 00000000000..ff2bd7130d9 --- /dev/null +++ b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/bridge/ReadableMapBuilder.kt @@ -0,0 +1,61 @@ +/* + * Copyright (c) Meta Platforms, Inc. and affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +package com.facebook.react.bridge + +/** + * Convenience class for building a [ReadableMap] in a Kotlin idiomatic way. You can use it as + * follows: + * ``` + * val array: ReadableArray = buildReadableArray { + * add("one") + * add(2) + * add(true) + * addNull() + * addMap { put("nestedKey", "nestedValue") } + * } + * ``` + */ +public inline fun buildReadableMap(builder: ReadableMapBuilder.() -> Unit): ReadableMap { + val map: WritableMap = Arguments.createMap() + ReadableMapBuilder(map).apply(builder) + return map +} + +public class ReadableMapBuilder(private val map: WritableMap) { + public fun put(key: String, value: String?) { + map.putString(key, value) + } + + public fun put(key: String, value: Int) { + map.putInt(key, value) + } + + public fun put(key: String, value: Boolean) { + map.putBoolean(key, value) + } + + public fun put(key: String, value: Double) { + map.putDouble(key, value) + } + + public fun put(key: String, value: Long) { + map.putDouble(key, value.toDouble()) + } + + public fun putNull(key: String) { + map.putNull(key) + } + + public fun putMap(key: String, builder: ReadableMapBuilder.() -> Unit) { + map.putMap(key, buildReadableMap(builder)) + } + + public fun putArray(key: String, builder: ReadableArrayBuilder.() -> Unit) { + map.putArray(key, buildReadableArray(builder)) + } +} diff --git a/packages/react-native/ReactAndroid/src/test/java/com/facebook/react/bridge/ReadableArrayBuilderTest.kt b/packages/react-native/ReactAndroid/src/test/java/com/facebook/react/bridge/ReadableArrayBuilderTest.kt new file mode 100644 index 00000000000..5d8887e409e --- /dev/null +++ b/packages/react-native/ReactAndroid/src/test/java/com/facebook/react/bridge/ReadableArrayBuilderTest.kt @@ -0,0 +1,70 @@ +/* + * Copyright (c) Meta Platforms, Inc. and affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +package com.facebook.react.bridge + +import com.facebook.testutils.shadows.ShadowArguments +import com.facebook.testutils.shadows.ShadowNativeArray +import com.facebook.testutils.shadows.ShadowNativeLoader +import com.facebook.testutils.shadows.ShadowNativeMap +import com.facebook.testutils.shadows.ShadowReadableNativeArray +import com.facebook.testutils.shadows.ShadowReadableNativeMap +import com.facebook.testutils.shadows.ShadowSoLoader +import com.facebook.testutils.shadows.ShadowWritableNativeArray +import com.facebook.testutils.shadows.ShadowWritableNativeMap +import org.assertj.core.api.Assertions.assertThat +import org.junit.Test +import org.junit.runner.RunWith +import org.robolectric.RobolectricTestRunner +import org.robolectric.annotation.Config + +@RunWith(RobolectricTestRunner::class) +@Config( + shadows = + [ + ShadowArguments::class, + ShadowSoLoader::class, + ShadowNativeLoader::class, + ShadowNativeArray::class, + ShadowNativeMap::class, + ShadowWritableNativeMap::class, + ShadowWritableNativeArray::class, + ShadowReadableNativeMap::class, + ShadowReadableNativeArray::class, + ]) +class ReadableArrayBuilderTest { + + @Test + fun `buildReadableArray creates array entries correctly`() { + val array: ReadableArray = buildReadableArray { + add("one") + add(2.0) + add(true) + addNull() + addMap { put("nestedKey", "nestedValue") } + } + + assertThat(array.toArrayList()).hasSize(5).contains("one", 2.0, true, null) + + val nestedMap = array.getMap(4) + checkNotNull(nestedMap) + assertThat(nestedMap.toHashMap()).containsEntry("nestedKey", "nestedValue") + } + + @Test + fun `buildReadableArray supports nested arrays`() { + val array: ReadableArray = buildReadableArray { + addArray { + add(1) + add(2) + } + } + + val nestedArray = array.getArray(0) + assertThat(nestedArray?.toArrayList()).isNotNull.containsExactly(1.0, 2.0) + } +} diff --git a/packages/react-native/ReactAndroid/src/test/java/com/facebook/react/bridge/ReadableMapBuilderTest.kt b/packages/react-native/ReactAndroid/src/test/java/com/facebook/react/bridge/ReadableMapBuilderTest.kt new file mode 100644 index 00000000000..c36461c2736 --- /dev/null +++ b/packages/react-native/ReactAndroid/src/test/java/com/facebook/react/bridge/ReadableMapBuilderTest.kt @@ -0,0 +1,86 @@ +/* + * Copyright (c) Meta Platforms, Inc. and affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +package com.facebook.react.bridge + +import com.facebook.testutils.shadows.ShadowArguments +import com.facebook.testutils.shadows.ShadowNativeArray +import com.facebook.testutils.shadows.ShadowNativeLoader +import com.facebook.testutils.shadows.ShadowNativeMap +import com.facebook.testutils.shadows.ShadowReadableNativeArray +import com.facebook.testutils.shadows.ShadowReadableNativeMap +import com.facebook.testutils.shadows.ShadowSoLoader +import com.facebook.testutils.shadows.ShadowWritableNativeArray +import com.facebook.testutils.shadows.ShadowWritableNativeMap +import org.assertj.core.api.Assertions.assertThat +import org.junit.Test +import org.junit.runner.RunWith +import org.robolectric.RobolectricTestRunner +import org.robolectric.annotation.Config + +@RunWith(RobolectricTestRunner::class) +@Config( + shadows = + [ + ShadowArguments::class, + ShadowSoLoader::class, + ShadowNativeLoader::class, + ShadowNativeArray::class, + ShadowNativeMap::class, + ShadowWritableNativeMap::class, + ShadowWritableNativeArray::class, + ShadowReadableNativeMap::class, + ShadowReadableNativeArray::class, + ]) +class ReadableMapBuilderTest { + + @Test + fun `buildReadableMap creates simple entries correctly`() { + val map: ReadableMap = buildReadableMap { + put("stringKey", "stringValue") + put("intKey", 42) + put("boolKey", false) + putNull("nullKey") + } + + assertThat(map.toHashMap()) + .hasSize(4) + .containsEntry("stringKey", "stringValue") + .containsEntry("intKey", 42.0) + .containsEntry("boolKey", false) + .containsEntry("nullKey", null) + } + + @Test + fun `buildReadableMap supports nested maps and arrays`() { + val map: ReadableMap = buildReadableMap { + putMap("nestedMap") { + put("innerString", "innerValue") + put("innerNumber", 123L) + } + putArray("nestedArray") { + add(10) + add(20) + add(30) + } + } + + // Nested Map + val nestedMap = map.getMap("nestedMap") + checkNotNull(nestedMap) + assertThat(nestedMap.toHashMap()) + .isNotNull + .hasSize(2) + .containsEntry("innerString", "innerValue") + .containsEntry("innerNumber", 123.0) + + // Nested Array inside Map + val nestedArray = map.getArray("nestedArray") + checkNotNull(nestedArray) + assertThat(nestedArray.toArrayList()).isNotNull.hasSize(3).containsExactly(10.0, 20.0, 30.0) + } +} diff --git a/packages/react-native/ReactAndroid/src/test/java/com/facebook/testutils/shadows/ShadowNativeArray.kt b/packages/react-native/ReactAndroid/src/test/java/com/facebook/testutils/shadows/ShadowNativeArray.kt index b6709dab341..dab1fbb534b 100644 --- a/packages/react-native/ReactAndroid/src/test/java/com/facebook/testutils/shadows/ShadowNativeArray.kt +++ b/packages/react-native/ReactAndroid/src/test/java/com/facebook/testutils/shadows/ShadowNativeArray.kt @@ -16,7 +16,7 @@ import org.robolectric.shadow.api.Shadow // Mockito can't mock native methods, so shadow the entire class instead @Implements(NativeArray::class) -public open class ShadowNativeArray { +open class ShadowNativeArray { var backingArray: JavaOnlyArray = JavaOnlyArray() @Deprecated( @@ -24,17 +24,17 @@ public open class ShadowNativeArray { ReplaceWith( "ShadowReadableNativeArray", "com.facebook.testutils.shadows.ShadowReadableNativeArray")) @Implements(ReadableNativeArray::class) - public class Readable : ShadowNativeArray() {} + class Readable : ShadowNativeArray() @Deprecated( "Use ShadowWritableNativeArray", ReplaceWith( "ShadowWritableNativeArray", "com.facebook.testutils.shadows.ShadowWritableNativeArray")) @Implements(WritableNativeArray::class) - public class Writable : ShadowNativeArray() {} + class Writable : ShadowNativeArray() - public companion object { - public fun getContents(array: NativeArray): List = + companion object { + fun getContents(array: NativeArray): List = (Shadow.extract(array) as ShadowNativeArray).backingArray.toArrayList() } } diff --git a/packages/react-native/ReactAndroid/src/test/java/com/facebook/testutils/shadows/ShadowNativeMap.kt b/packages/react-native/ReactAndroid/src/test/java/com/facebook/testutils/shadows/ShadowNativeMap.kt index 24e14b920e8..2f7a535fcc8 100644 --- a/packages/react-native/ReactAndroid/src/test/java/com/facebook/testutils/shadows/ShadowNativeMap.kt +++ b/packages/react-native/ReactAndroid/src/test/java/com/facebook/testutils/shadows/ShadowNativeMap.kt @@ -24,14 +24,14 @@ open class ShadowNativeMap { ReplaceWith( "ShadowReadableNativeMap", "com.facebook.testutils.shadows.ShadowReadableNativeMap")) @Implements(ReadableNativeMap::class) - public class Readable : ShadowNativeMap() {} + class Readable : ShadowNativeMap() @Deprecated( "Use ShadowWritableNativeMap", ReplaceWith( "ShadowWritableNativeMap", "com.facebook.testutils.shadows.ShadowWritableNativeMap")) @Implements(WritableNativeMap::class) - public class Writable : ShadowNativeMap() {} + class Writable : ShadowNativeMap() companion object { fun getContents(map: NativeMap): Map =