expo-modules-core 0.6.4 → 0.7.0

package/CHANGELOG.md

@@ -10,6 +10,26 @@
 
 ### 💡 Others
 
+## 0.7.0 — 2022-01-26
+
+### 🎉 New features
+
+- Allow accessing `RCTBridge` from the modules on iOS. ([#15816](https://github.com/expo/expo/pull/15816) by [@tsapeta](https://github.com/tsapeta))
+- Added support for native callbacks through the view props in Sweet API on iOS. ([#15731](https://github.com/expo/expo/pull/15731) by [@tsapeta](https://github.com/tsapeta))
+- Added support for native callbacks through the view props in Sweet API on Android. ([#15743](https://github.com/expo/expo/pull/15743) by [@lukmccall](https://github.com/lukmccall))
+- The `ModuleDefinition` will use class name if the `name` component wasn't provided in Sweet API on Android. ([#15738](https://github.com/expo/expo/pull/15738) by [@lukmccall](https://github.com/lukmccall))
+- Added `onViewDestroys` component to the `ViewManager` in Sweet API on Android. ([#15740](https://github.com/expo/expo/pull/15740) by [@lukmccall](https://github.com/lukmccall))
+- Added shortened `constants` component that takes `vargs Pair<String, Any?>` as an argument in Sweet API on Android. ([#15742](https://github.com/expo/expo/pull/15742) by [@lukmccall](https://github.com/lukmccall))
+- Introduced the concept of chainable exceptions in Sweet API on iOS. ([#15813](https://github.com/expo/expo/pull/15813) by [@tsapeta](https://github.com/tsapeta))
+- Sweet function closures can throw errors on iOS. ([#15849](https://github.com/expo/expo/pull/15849) by [@tsapeta](https://github.com/tsapeta))
+- Add `requireNativeModule` function to replace accessing native modules from `NativeModulesProxy`. ([#15848](https://github.com/expo/expo/pull/15848) by [@tsapeta](https://github.com/tsapeta))
+- Implemented basic functionality of JSI host object to replace `NativeModulesProxy` on iOS. ([#15847](https://github.com/expo/expo/pull/15847) by [@tsapeta](https://github.com/tsapeta))
+
+### 🐛 Bug fixes
+
+- It's no longer possible to directly call methods from the `ModuleDefinition` in the `ViewManagers` on Android. ([#15741](https://github.com/expo/expo/pull/15741) by [@lukmccall](https://github.com/lukmccall))
+- Fix compatibility with react-native 0.66. ([#15914](https://github.com/expo/expo/pull/15914) by [@kudo](https://github.com/kudo))
+
 ## 0.6.4 — 2022-01-05
 
 ### 🐛 Bug fixes

package/README.md

@@ -4,7 +4,7 @@ The core of Expo Modules architecture.
 
 # Installation in managed Expo projects
 
-For managed [managed](https://docs.expo.io/versions/latest/introduction/managed-vs-bare/) Expo projects, please follow the installation instructions in the [API documentation for the latest stable release](#api-documentation). If you follow the link and there is no documentation available then this library is not yet usable within managed projects — it is likely to be included in an upcoming Expo SDK release.
+For [managed](https://docs.expo.io/versions/latest/introduction/managed-vs-bare/) Expo projects, please follow the installation instructions in the [API documentation for the latest stable release](#api-documentation). If you follow the link and there is no documentation available then this library is not yet usable within managed projects — it is likely to be included in an upcoming Expo SDK release.
 
 # Installation in bare React Native projects
 

package/android/build.gradle

@@ -3,7 +3,7 @@ apply plugin: 'kotlin-android'
 apply plugin: 'maven'
 
 group = 'host.exp.exponent'
-version = '0.6.4'
+version = '0.7.0'
 
 buildscript {
   // Simple helper that allows the root project to override versions declared by this library.
@@ -16,7 +16,7 @@ buildscript {
   }
 
   dependencies {
-    classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${safeExtGet('kotlinVersion', '1.4.21')}")
+    classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${safeExtGet('kotlinVersion', '1.6.10')}")
   }
 }
 
@@ -58,7 +58,7 @@ android {
     targetSdkVersion safeExtGet("targetSdkVersion", 30)
     consumerProguardFiles 'proguard-rules.pro'
     versionCode 1
-    versionName "0.6.4"
+    versionName "0.7.0"
   }
   lintOptions {
     abortOnError false
@@ -81,8 +81,8 @@ android {
 }
 
 dependencies {
-  implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:${safeExtGet('kotlinVersion', '1.4.21')}"
-  implementation "org.jetbrains.kotlin:kotlin-reflect:${safeExtGet('kotlinVersion', '1.4.21')}"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:${safeExtGet('kotlinVersion', '1.6.10')}"
+  implementation "org.jetbrains.kotlin:kotlin-reflect:${safeExtGet('kotlinVersion', '1.6.10')}"
   implementation 'androidx.annotation:annotation:1.2.0'
 
   // used only in `expo.modules.core.errors.ModuleDestroyedException` for API export

package/android/src/main/java/expo/modules/kotlin/AppContext.kt

@@ -15,6 +15,7 @@ import expo.modules.interfaces.imageloader.ImageLoaderInterface
 import expo.modules.interfaces.permissions.Permissions
 import expo.modules.interfaces.sensors.SensorServiceInterface
 import expo.modules.interfaces.taskManager.TaskManagerInterface
+import expo.modules.kotlin.defaultmodules.ErrorManagerModule
 import expo.modules.kotlin.events.EventName
 import expo.modules.kotlin.events.KEventEmitterWrapper
 import expo.modules.kotlin.events.OnActivityResultPayload
@@ -26,7 +27,10 @@ class AppContext(
   val legacyModuleRegistry: expo.modules.core.ModuleRegistry,
   private val reactContextHolder: WeakReference<ReactApplicationContext>
 ) {
-  val registry = ModuleRegistry(WeakReference(this)).register(modulesProvider)
+  val registry = ModuleRegistry(WeakReference(this)).apply {
+    register(ErrorManagerModule())
+    register(modulesProvider)
+  }
   private val reactLifecycleDelegate = ReactLifecycleDelegate(this)
 
   init {
@@ -128,6 +132,12 @@ class AppContext(
     )
   }
 
+  internal val callbackInvoker: EventEmitter?
+    get() = legacyModule()
+
+  internal val errorManager: ErrorManagerModule?
+    get() = registry.getModule()
+
   fun onDestroy() {
     reactContextHolder.get()?.removeLifecycleEventListener(reactLifecycleDelegate)
     registry.post(EventName.MODULE_DESTROY)

package/android/src/main/java/expo/modules/kotlin/DynamicExtenstions.kt

@@ -3,7 +3,9 @@ package expo.modules.kotlin
 import com.facebook.react.bridge.Dynamic
 
 inline fun <T> Dynamic.recycle(block: Dynamic.() -> T): T {
-  val result = block(this)
-  this.recycle()
-  return result
+  try {
+    return block(this)
+  } finally {
+    this.recycle()
+  }
 }

package/android/src/main/java/expo/modules/kotlin/KPromiseWrapper.kt

@@ -2,17 +2,23 @@ package expo.modules.kotlin
 
 import android.os.Bundle
 import com.facebook.react.bridge.Arguments
+import expo.modules.kotlin.records.Record
+import expo.modules.kotlin.records.toJSMap
 
 class KPromiseWrapper(
   private val bridgePromise: com.facebook.react.bridge.Promise
 ) : Promise {
 
+  @Suppress("UNCHECKED_CAST")
   override fun resolve(value: Any?) {
     bridgePromise.resolve(
       when (value) {
         is Unit -> null
-        is Bundle -> Arguments.fromBundle(value as Bundle?)
-        is List<*> -> Arguments.fromList(value as List<*>?)
+        is Bundle -> Arguments.fromBundle(value)
+        is List<*> -> Arguments.fromList(value)
+        is Array<*> -> Arguments.fromArray(value)
+        is Map<*, *> -> Arguments.makeNativeMap(value as Map<String, Any?>) // TODO(@lukmccall): add more sophisticated conversion method
+        is Record -> value.toJSMap()
         else -> value
       }
     )

package/android/src/main/java/expo/modules/kotlin/KotlinInteropModuleRegistry.kt

@@ -3,6 +3,8 @@ package expo.modules.kotlin
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReadableArray
 import com.facebook.react.uimanager.ViewManager
+import expo.modules.kotlin.exception.CodedException
+import expo.modules.kotlin.exception.UnexpectedException
 import expo.modules.kotlin.views.GroupViewManagerWrapper
 import expo.modules.kotlin.views.SimpleViewManagerWrapper
 import expo.modules.kotlin.views.ViewManagerWrapperDelegate
@@ -18,7 +20,7 @@ class KotlinInteropModuleRegistry(
   legacyModuleRegistry: expo.modules.core.ModuleRegistry,
   reactContext: WeakReference<ReactApplicationContext>
 ) {
-  private val appContext = AppContext(modulesProvider, legacyModuleRegistry, reactContext)
+  internal val appContext = AppContext(modulesProvider, legacyModuleRegistry, reactContext)
 
   private val registry: ModuleRegistry
     get() = appContext.registry
@@ -26,9 +28,16 @@ class KotlinInteropModuleRegistry(
   fun hasModule(name: String): Boolean = registry.hasModule(name)
 
   fun callMethod(moduleName: String, method: String, arguments: ReadableArray, promise: Promise) {
-    registry
-      .getModuleHolder(moduleName)
-      ?.call(method, arguments, promise)
+    try {
+      requireNotNull(
+        registry.getModuleHolder(moduleName)
+      ) { "Trying to call '$method' on the non-existing module '$moduleName'" }
+        .call(method, arguments, promise)
+    } catch (e: CodedException) {
+      promise.reject(e)
+    } catch (e: Throwable) {
+      promise.reject(UnexpectedException(e))
+    }
   }
 
   fun exportedModulesConstants(): Map<ModuleName, ModuleConstants> {

package/android/src/main/java/expo/modules/kotlin/ModuleHolder.kt

@@ -1,23 +1,24 @@
 package expo.modules.kotlin
 
 import com.facebook.react.bridge.ReadableArray
-import expo.modules.core.utilities.ifNull
 import expo.modules.kotlin.events.BasicEventListener
 import expo.modules.kotlin.events.EventListenerWithPayload
 import expo.modules.kotlin.events.EventListenerWithSenderAndPayload
 import expo.modules.kotlin.events.EventName
+import expo.modules.kotlin.exception.FunctionCallException
 import expo.modules.kotlin.exception.MethodNotFoundException
+import expo.modules.kotlin.exception.exceptionDecorator
 import expo.modules.kotlin.modules.Module
 
 class ModuleHolder(val module: Module) {
   val definition = module.definition()
   val name get() = definition.name
 
-  fun call(methodName: String, args: ReadableArray, promise: Promise) {
-    val method = definition.methods[methodName].ifNull {
-      promise.reject(MethodNotFoundException(methodName, definition.name))
-      return
-    }
+  fun call(methodName: String, args: ReadableArray, promise: Promise) = exceptionDecorator({
+    FunctionCallException(methodName, definition.name, it)
+  }) {
+    val method = definition.methods[methodName]
+      ?: throw MethodNotFoundException()
 
     method.call(args, promise)
   }

package/android/src/main/java/expo/modules/kotlin/ModuleRegistry.kt

@@ -7,7 +7,8 @@ import java.lang.ref.WeakReference
 class ModuleRegistry(
   private val appContext: WeakReference<AppContext>
 ) : Iterable<ModuleHolder> {
-  private val registry = mutableMapOf<String, ModuleHolder>()
+  @PublishedApi
+  internal val registry = mutableMapOf<String, ModuleHolder>()
 
   fun register(module: Module) {
     val holder = ModuleHolder(module)
@@ -27,6 +28,10 @@ class ModuleRegistry(
 
   fun getModule(name: String): Module? = registry[name]?.module
 
+  inline fun <reified T> getModule(): T? {
+    return registry.values.find { it.module is T }?.module as? T
+  }
+
   fun getModuleHolder(name: String): ModuleHolder? = registry[name]
 
   fun getModuleHolder(module: Module): ModuleHolder? =

package/android/src/main/java/expo/modules/kotlin/Promise.kt

@@ -8,6 +8,6 @@ interface Promise {
   fun reject(code: String, message: String?, cause: Throwable?)
 
   fun reject(exception: CodedException) {
-    reject(exception.code, exception.message, exception.cause)
+    reject(exception.code, exception.localizedMessage, exception.cause)
   }
 }

package/android/src/main/java/expo/modules/kotlin/callbacks/Callback.kt

@@ -0,0 +1,5 @@
+package expo.modules.kotlin.callbacks
+
+fun interface Callback<T> {
+  operator fun invoke(arg: T)
+}

package/android/src/main/java/expo/modules/kotlin/callbacks/ViewCallback.kt

@@ -0,0 +1,28 @@
+package expo.modules.kotlin.callbacks
+
+import android.os.Bundle
+import android.view.View
+import com.facebook.react.bridge.ReactContext
+import expo.modules.adapters.react.NativeModulesProxy
+import expo.modules.kotlin.modules.Module
+import kotlin.reflect.KType
+
+class ViewCallback<T>(
+  private val name: String,
+  private val type: KType,
+  private val view: View
+) : Callback<T> {
+  internal lateinit var module: Module
+
+  override operator fun invoke(arg: T) {
+    val reactContext = view.context as ReactContext
+    val nativeModulesProxy = reactContext
+      .catalystInstance
+      ?.getNativeModule("NativeUnimoduleProxy") as? NativeModulesProxy
+      ?: return
+    val appContext = nativeModulesProxy.kotlinInteropModuleRegistry.appContext
+
+    // TODO(@lukmccall): handles other types
+    appContext.callbackInvoker?.emit(view.id, name, arg as Bundle)
+  }
+}

package/android/src/main/java/expo/modules/kotlin/callbacks/ViewCallbackDelegate.kt

@@ -0,0 +1,27 @@
+@file:OptIn(ExperimentalStdlibApi::class)
+
+package expo.modules.kotlin.callbacks
+
+import android.view.View
+import java.lang.ref.WeakReference
+import kotlin.reflect.KProperty
+import kotlin.reflect.KType
+import kotlin.reflect.typeOf
+
+class ViewCallbackDelegate<T>(private val type: KType, view: View) {
+  private val viewHolder = WeakReference(view)
+  internal var isValidated = false
+
+  operator fun getValue(thisRef: View, property: KProperty<*>): Callback<T> {
+    if (!isValidated) {
+      throw IllegalStateException("You have to export this property as a callback in the `ViewManager`.")
+    }
+
+    val view = viewHolder.get() ?: throw IllegalStateException("Can't send an event from the view that is deallocated.")
+    return ViewCallback(property.name, type, view)
+  }
+}
+
+inline fun <reified T> View.callback(): ViewCallbackDelegate<T> {
+  return ViewCallbackDelegate(typeOf<T>(), this)
+}

package/android/src/main/java/expo/modules/kotlin/defaultmodules/ErrorManagerModule.kt

@@ -0,0 +1,25 @@
+package expo.modules.kotlin.defaultmodules
+
+import android.os.Bundle
+import expo.modules.kotlin.exception.CodedException
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+private const val onNewException = "ExpoModulesCoreErrorManager.onNewException"
+
+class ErrorManagerModule : Module() {
+  override fun definition() = ModuleDefinition {
+    name("ExpoModulesCoreErrorManager")
+    events(onNewException)
+  }
+
+  fun reportExceptionToLogBox(codedException: CodedException) {
+    val eventEmitter = appContext.eventEmitter(this) ?: return
+    eventEmitter.emit(
+      onNewException,
+      Bundle().apply {
+        putString("message", codedException.message ?: codedException.toString())
+      }
+    )
+  }
+}

package/android/src/main/java/expo/modules/kotlin/exception/CodedException.kt

@@ -1,5 +1,6 @@
 package expo.modules.kotlin.exception
 
+import com.facebook.react.bridge.ReadableType
 import java.util.*
 import kotlin.reflect.KType
 
@@ -17,7 +18,7 @@ open class CodedException(
   val code
     get() = providedCode ?: inferCode(javaClass)
 
-  constructor(code: String, message: String, cause: Throwable?) : this(message, cause) {
+  constructor(code: String, message: String?, cause: Throwable?) : this(message, cause) {
     providedCode = code
   }
 
@@ -47,24 +48,83 @@ internal class IncompatibleArgTypeException(
   desiredType: KType,
   cause: Throwable? = null
 ) : CodedException(
-  message = "Argument type $argumentType is not compatible with expected type $desiredType.",
+  message = "Argument type '$argumentType' is not compatible with expected type '$desiredType'.",
   cause = cause
 )
 
 internal class MissingTypeConverter(
   forType: KType
 ) : CodedException(
-  message = "Cannot find type converter for $forType.",
+  message = "Cannot find type converter for '$forType'.",
 )
 
 internal class InvalidArgsNumberException(received: Int, expected: Int) :
   CodedException(message = "Received $received arguments, but $expected was expected.")
 
-internal class MethodNotFoundException(methodName: String, moduleName: String) :
-  CodedException(message = "Cannot fund method $methodName in module $moduleName")
+internal class MethodNotFoundException :
+  CodedException(message = "Method does not exist.")
 
-internal class NullArgumentException(desiredType: KType) :
-  CodedException(message = "Cannot assigned null to not nullable type $desiredType")
+internal class NullArgumentException :
+  CodedException(message = "Cannot assigned null to not nullable type.")
 
 internal class UnexpectedException(val throwable: Throwable) :
-  CodedException(throwable)
+  CodedException(message = throwable.toString(), throwable)
+
+/**
+ * A base class for all exceptions used in `exceptionDecorator` function.
+ */
+internal open class DecoratedException(
+  message: String,
+  cause: CodedException,
+) : CodedException(
+  cause.code,
+  message = "$message${System.lineSeparator()}→ Caused by: ${cause.localizedMessage ?: cause}",
+  cause
+)
+
+internal class FunctionCallException(
+  methodName: String,
+  moduleName: String,
+  cause: CodedException
+) : DecoratedException(
+  message = "Call to function '$moduleName.$methodName' has been rejected.",
+  cause,
+)
+
+internal class ArgumentCastException(
+  argDesiredType: KType,
+  argIndex: Int,
+  providedType: ReadableType,
+  cause: CodedException,
+) : DecoratedException(
+  message = "Argument at index '$argIndex' couldn't be casted to type '$argDesiredType' (received '$providedType').",
+  cause,
+)
+
+internal class FieldCastException(
+  fieldName: String,
+  fieldType: KType,
+  providedType: ReadableType,
+  cause: CodedException
+) : DecoratedException(
+  message = "Cannot cast '${providedType.name}' for field '$fieldName' ('$fieldType').",
+  cause
+)
+
+internal class RecordCastException(
+  recordType: KType,
+  cause: CodedException
+) : DecoratedException(
+  message = "Cannot create a record of the type: '$recordType'.",
+  cause
+)
+
+internal class CollectionElementCastException(
+  collectionType: KType,
+  elementType: KType,
+  providedType: ReadableType,
+  cause: CodedException
+) : DecoratedException(
+  message = "Cannot cast '${providedType.name}' to '$elementType' required by the collection of type: '$collectionType'.",
+  cause
+)

package/android/src/main/java/expo/modules/kotlin/exception/ExceptionDecorator.kt

@@ -0,0 +1,11 @@
+package expo.modules.kotlin.exception
+
+internal inline fun <T> exceptionDecorator(decoratorBlock: (e: CodedException) -> Throwable, block: () -> T): T {
+  return try {
+    block()
+  } catch (e: CodedException) {
+    throw decoratorBlock(e)
+  } catch (e: Throwable) {
+    throw decoratorBlock(UnexpectedException(e))
+  }
+}

package/android/src/main/java/expo/modules/kotlin/methods/AnyMethod.kt

@@ -2,31 +2,26 @@ package expo.modules.kotlin.methods
 
 import com.facebook.react.bridge.ReadableArray
 import expo.modules.kotlin.Promise
+import expo.modules.kotlin.exception.ArgumentCastException
 import expo.modules.kotlin.exception.CodedException
 import expo.modules.kotlin.exception.InvalidArgsNumberException
-import expo.modules.kotlin.exception.UnexpectedException
+import expo.modules.kotlin.exception.exceptionDecorator
 import expo.modules.kotlin.iterator
 import expo.modules.kotlin.recycle
 import expo.modules.kotlin.types.AnyType
-import kotlin.jvm.Throws
 
 abstract class AnyMethod(
   protected val name: String,
   private val desiredArgsTypes: Array<AnyType>
 ) {
+  @Throws(CodedException::class)
   fun call(args: ReadableArray, promise: Promise) {
     if (desiredArgsTypes.size != args.size()) {
-      promise.reject(InvalidArgsNumberException(args.size(), desiredArgsTypes.size))
-      return
-    }
-    try {
-      val convertedArgs = convertArgs(args)
-      callImplementation(convertedArgs, promise)
-    } catch (codedError: CodedException) {
-      promise.reject(codedError)
-    } catch (e: Throwable) {
-      promise.reject(UnexpectedException(e))
+      throw InvalidArgsNumberException(args.size(), desiredArgsTypes.size)
     }
+
+    val convertedArgs = convertArgs(args)
+    callImplementation(convertedArgs, promise)
   }
 
   @Throws(CodedException::class)
@@ -40,9 +35,13 @@ abstract class AnyMethod(
     val argIterator = args.iterator()
     desiredArgsTypes
       .withIndex()
-      .forEach { (index, type) ->
+      .forEach { (index, desiredType) ->
         argIterator.next().recycle {
-          finalArgs[index] = type.convert(this)
+          exceptionDecorator({ cause ->
+            ArgumentCastException(desiredType.kType, index, type, cause)
+          }) {
+            finalArgs[index] = desiredType.convert(this)
+          }
         }
       }
     return finalArgs

package/android/src/main/java/expo/modules/kotlin/modules/DefinitionMarker.kt

@@ -0,0 +1,4 @@
+package expo.modules.kotlin.modules
+
+@DslMarker
+internal annotation class DefinitionMarker

package/android/src/main/java/expo/modules/kotlin/modules/Module.kt

@@ -4,6 +4,7 @@ import android.os.Bundle
 import expo.modules.kotlin.AppContext
 
 abstract class Module {
+  @Suppress("PropertyName")
   internal var _appContext: AppContext? = null
 
   private val moduleEventEmitter by lazy { appContext.eventEmitter(this) }
@@ -19,6 +20,6 @@ abstract class Module {
 }
 
 @Suppress("FunctionName")
-inline fun ModuleDefinition(block: ModuleDefinitionBuilder.() -> Unit): ModuleDefinitionData {
-  return ModuleDefinitionBuilder().also(block).build()
+inline fun Module.ModuleDefinition(block: ModuleDefinitionBuilder.() -> Unit): ModuleDefinitionData {
+  return ModuleDefinitionBuilder(this).also(block).build()
 }

package/android/src/main/java/expo/modules/kotlin/modules/ModuleDefinitionBuilder.kt

@@ -31,7 +31,8 @@ import expo.modules.kotlin.views.ViewManagerDefinition
 import expo.modules.kotlin.views.ViewManagerDefinitionBuilder
 import kotlin.reflect.typeOf
 
-class ModuleDefinitionBuilder {
+@DefinitionMarker
+class ModuleDefinitionBuilder(private val module: Module? = null) {
   private var name: String? = null
   private var constantsProvider = { emptyMap<String, Any?>() }
   private var eventsDefinition: EventsDefinition? = null
@@ -46,8 +47,10 @@ class ModuleDefinitionBuilder {
   internal val eventListeners = mutableMapOf<EventName, EventListener>()
 
   fun build(): ModuleDefinitionData {
+    val moduleName = name ?: module?.javaClass?.simpleName
+
     return ModuleDefinitionData(
-      requireNotNull(name),
+      requireNotNull(moduleName),
       constantsProvider,
       methods,
       viewManagerDefinition,
@@ -56,14 +59,27 @@ class ModuleDefinitionBuilder {
     )
   }
 
+  /**
+   * Sets the name of the module that is exported to the JavaScript world.
+   */
   fun name(name: String) {
     this.name = name
   }
 
+  /**
+   * Definition function setting the module's constants to export.
+   */
   fun constants(constantsProvider: () -> Map<String, Any?>) {
     this.constantsProvider = constantsProvider
   }
 
+  /**
+   * Definition of the module's constants to export.
+   */
+  fun constants(vararg constants: Pair<String, Any?>) {
+    constantsProvider = { constants.toMap() }
+  }
+
   @JvmName("methodWithoutArgs")
   inline fun function(
     name: String,
@@ -167,6 +183,9 @@ class ModuleDefinitionBuilder {
     }
   }
 
+  /**
+   * Creates the view manager definition that scopes other view-related definitions.
+   */
   inline fun viewManager(body: ViewManagerDefinitionBuilder.() -> Unit) {
     require(viewManagerDefinition == null) { "The module definition may have exported only one view manager." }
 
@@ -175,22 +194,37 @@ class ModuleDefinitionBuilder {
     viewManagerDefinition = viewManagerDefinitionBuilder.build()
   }
 
+  /**
+   * Creates module's lifecycle listener that is called right after the module initialization.
+   */
   inline fun onCreate(crossinline body: () -> Unit) {
     eventListeners[EventName.MODULE_CREATE] = BasicEventListener(EventName.MODULE_CREATE) { body() }
   }
 
+  /**
+   * Creates module's lifecycle listener that is called when the module is about to be deallocated.
+   */
   inline fun onDestroy(crossinline body: () -> Unit) {
     eventListeners[EventName.MODULE_DESTROY] = BasicEventListener(EventName.MODULE_DESTROY) { body() }
   }
 
+  /**
+   * Creates module's lifecycle listener that is called right after the activity is resumed.
+   */
   inline fun onActivityEntersForeground(crossinline body: () -> Unit) {
     eventListeners[EventName.ACTIVITY_ENTERS_FOREGROUND] = BasicEventListener(EventName.ACTIVITY_ENTERS_FOREGROUND) { body() }
   }
 
+  /**
+   * Creates module's lifecycle listener that is called right after the activity is paused.
+   */
   inline fun onActivityEntersBackground(crossinline body: () -> Unit) {
     eventListeners[EventName.ACTIVITY_ENTERS_BACKGROUND] = BasicEventListener(EventName.ACTIVITY_ENTERS_BACKGROUND) { body() }
   }
 
+  /**
+   * Creates module's lifecycle listener that is called right after the activity is destroyed.
+   */
   inline fun onActivityDestroys(crossinline body: () -> Unit) {
     eventListeners[EventName.ACTIVITY_DESTROYS] = BasicEventListener(EventName.ACTIVITY_DESTROYS) { body() }
   }
@@ -203,23 +237,29 @@ class ModuleDefinitionBuilder {
   }
 
   /**
-   * Method that is invoked when the first event listener is added.
+   * Creates module's lifecycle listener that is called right after the first event listener is added.
    */
   inline fun onStartObserving(crossinline body: () -> Unit) {
     function("startObserving", body)
   }
 
   /**
-   * Method that is invoked when all event listeners are removed.
+   * Creates module's lifecycle listener that is called right after all event listeners are removed.
    */
   inline fun onStopObserving(crossinline body: () -> Unit) {
     function("stopObserving", body)
   }
 
+  /**
+   * Creates module's lifecycle listener that is called right after the new intent was received.
+   */
   inline fun onNewIntent(crossinline body: (Intent) -> Unit) {
     eventListeners[EventName.ON_NEW_INTENT] = EventListenerWithPayload<Intent>(EventName.ON_NEW_INTENT) { body(it) }
   }
 
+  /**
+   * Creates module's lifecycle listener that is called right after the activity has received a result.
+   */
   inline fun onActivityResult(crossinline body: (Activity, OnActivityResultPayload) -> Unit) {
     eventListeners[EventName.ON_ACTIVITY_RESULT] =
       EventListenerWithSenderAndPayload<Activity, OnActivityResultPayload>(EventName.ON_ACTIVITY_RESULT) { sender, payload -> body(sender, payload) }