Add system property to control snapshot notifier default (#615)

Since the Compose UI snapshot notifier is a global singleton that can be started in one place, this allows you to also switch Molecule's default in that same location. Much easier than updating tens or hundreds of call sites.

Author: JakeWharton

CHANGELOG.md

@@ -3,7 +3,10 @@
 ## [Unreleased]
 
 New:
-- Add `SnapshotNotifier` enum to control whether Molecule automatically sends snapshot apply notifications. If you are using Molecule with another Compose-based library in a single application, you may want to disable our snapshot notification. See the enum for details on when that is appropriate.
+- Add `SnapshotNotifier` enum to control whether Molecule automatically sends snapshot apply notifications.
+  If you are using Molecule with another Compose-based library in a single application, you may want to disable our snapshot notification.
+  See the enum for details on when that is appropriate.
+  Additionally, the `app.cash.molecule.snapshotNotifier` system property can be set to one of the enum entry names to control the default process-wide.
 
 Changed:
 - Any specified additional coroutine context elements will now be honored in the coroutine used internally with `RecompositionMode.Immediate` to send frames and cause recomposition to occur. This is observable, most notably, when a `CoroutineDispatcher` is included, as now recompositions which occur after the first, synchronous one will occur on that dispatcher.

molecule-runtime/build.gradle

@@ -55,6 +55,11 @@ kotlin {
         }
         it.group("watchos") {}
       }
+      it.group('nonJava') {
+        it.group('native') {}
+        it.withJs()
+        it.withWasmJs()
+      }
     }
   }
 
@@ -84,14 +89,17 @@ kotlin {
       }
     }
 
+    // We use a common folder instead of a common source set because there is no commonizer
+    // which exposes the Java APIs across these two targets.
+    androidMain { kotlin.srcDir('src/javaMain/kotlin') }
+    androidTest { kotlin.srcDir('src/javaTest/kotlin') }
+    jvmMain { kotlin.srcDir('src/javaMain/kotlin') }
+    jvmTest { kotlin.srcDir('src/javaTest/kotlin') }
+
     // We use a common folder instead of a common source set because there is no commonizer
     // which exposes the browser APIs across these two targets.
-    jsMain {
-      kotlin.srcDir('src/browserMain/kotlin')
-    }
-    wasmJsMain {
-      kotlin.srcDir('src/browserMain/kotlin')
-    }
+    jsMain { kotlin.srcDir('src/browserMain/kotlin') }
+    wasmJsMain { kotlin.srcDir('src/browserMain/kotlin') }
   }
 }
 
@@ -118,6 +126,7 @@ android {
   sourceSets {
     androidTest {
       java.srcDirs += 'src/commonTest/kotlin'
+      java.srcDirs += 'src/javaTest/kotlin'
     }
   }
 

molecule-runtime/src/commonMain/kotlin/app/cash/molecule/SnapshotNotifier.kt

@@ -15,6 +15,8 @@
  */
 package app.cash.molecule
 
+import app.cash.molecule.SnapshotNotifier.WhileActive
+
 /**
  * The different snapshot notification modes of Molecule.
  *
@@ -25,6 +27,10 @@ package app.cash.molecule
  * have one in place, whereas applications that only use Molecule need its automatic registering
  * of this notifier.
  *
+ * On the JVM and Android, Molecule will read the `app.cash.molecule.snapshotNotifier` system
+ * property in order to determine the default mechanism. The value is parsed with [enumValueOf],
+ * or else defaults to [WhileActive] if not set or the property does not parse to a value.
+ *
  * @see androidx.compose.runtime.snapshots.Snapshot.sendApplyNotifications
  */
 public enum class SnapshotNotifier {

molecule-runtime/src/commonMain/kotlin/app/cash/molecule/molecule.kt

@@ -39,7 +39,7 @@ import kotlinx.coroutines.launch
 public fun <T> moleculeFlow(mode: RecompositionMode, body: @Composable () -> T): Flow<T> {
   return moleculeFlow(
     mode = mode,
-    snapshotNotifier = SnapshotNotifier.WhileActive,
+    snapshotNotifier = defaultSnapshotNotifier(),
     body = body,
   )
 }
@@ -50,7 +50,7 @@ public fun <T> moleculeFlow(mode: RecompositionMode, body: @Composable () -> T):
  */
 public fun <T> moleculeFlow(
   mode: RecompositionMode,
-  snapshotNotifier: SnapshotNotifier = SnapshotNotifier.WhileActive,
+  snapshotNotifier: SnapshotNotifier = defaultSnapshotNotifier(),
   body: @Composable () -> T,
 ): Flow<T> {
   return when (mode) {
@@ -136,7 +136,7 @@ public fun <T> CoroutineScope.launchMolecule(
   return launchMolecule(
     mode = mode,
     context = context,
-    snapshotNotifier = SnapshotNotifier.WhileActive,
+    snapshotNotifier = defaultSnapshotNotifier(),
     body = body,
   )
 }
@@ -151,7 +151,7 @@ public fun <T> CoroutineScope.launchMolecule(
 public fun <T> CoroutineScope.launchMolecule(
   mode: RecompositionMode,
   context: CoroutineContext = EmptyCoroutineContext,
-  snapshotNotifier: SnapshotNotifier = SnapshotNotifier.WhileActive,
+  snapshotNotifier: SnapshotNotifier = defaultSnapshotNotifier(),
   body: @Composable () -> T,
 ): StateFlow<T> {
   var flow: MutableStateFlow<T>? = null
@@ -199,7 +199,7 @@ public fun <T> CoroutineScope.launchMolecule(
     mode = mode,
     emitter = emitter,
     context = context,
-    snapshotNotifier = SnapshotNotifier.WhileActive,
+    snapshotNotifier = defaultSnapshotNotifier(),
     body = body,
   )
 }
@@ -218,7 +218,7 @@ public fun <T> CoroutineScope.launchMolecule(
   mode: RecompositionMode,
   emitter: (value: T) -> Unit,
   context: CoroutineContext = EmptyCoroutineContext,
-  snapshotNotifier: SnapshotNotifier = SnapshotNotifier.WhileActive,
+  snapshotNotifier: SnapshotNotifier = defaultSnapshotNotifier(),
   body: @Composable () -> T,
 ) {
   val clockContext = when (mode) {

molecule-runtime/src/commonMain/kotlin/app/cash/molecule/platform.kt

@@ -0,0 +1,18 @@
+/*
+ * Copyright (C) 2025 Square, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package app.cash.molecule
+
+internal expect fun defaultSnapshotNotifier(): SnapshotNotifier

molecule-runtime/src/commonTest/kotlin/app/cash/molecule/MoleculeTest.kt

@@ -459,5 +459,9 @@ class MoleculeTest {
     job.cancelAndJoin()
   }
 
+  @Test fun defaultSnapshotNotifierChangeDetector() {
+    assertThat(defaultSnapshotNotifier()).isEqualTo(WhileActive)
+  }
+
   private suspend fun <T> Channel<T>.awaitValue(): T = withTimeout(1000) { receive() }
 }

molecule-runtime/src/javaMain/kotlin/app/cash/molecule/platform.kt

@@ -0,0 +1,24 @@
+/*
+ * Copyright (C) 2025 Square, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package app.cash.molecule
+
+internal actual fun defaultSnapshotNotifier(): SnapshotNotifier {
+  return System.getProperty("app.cash.molecule.snapshotNotifier")
+    ?.let { property ->
+      runCatching { SnapshotNotifier.valueOf(property) }.getOrNull()
+    }
+    ?: SnapshotNotifier.WhileActive
+}

molecule-runtime/src/javaTest/kotlin/app/cash/molecule/DefaultSnapshotNotifierPropertyTest.kt

@@ -0,0 +1,54 @@
+/*
+ * Copyright (C) 2025 Square, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package app.cash.molecule
+
+import app.cash.molecule.SnapshotNotifier.External
+import app.cash.molecule.SnapshotNotifier.WhileActive
+import assertk.assertThat
+import assertk.assertions.isEqualTo
+import kotlin.test.Test
+
+// Note: We do not share this constant with the production code to verify its value doesn't change.
+private const val property = "app.cash.molecule.snapshotNotifier"
+
+class DefaultSnapshotNotifierPropertyTest {
+  @Test fun propertyEmpty() {
+    System.setProperty(property, "")
+    try {
+      assertThat(defaultSnapshotNotifier()).isEqualTo(WhileActive)
+    } finally {
+      System.clearProperty(property)
+    }
+  }
+
+  @Test fun propertyInvalid() {
+    System.setProperty(property, "sup")
+    try {
+      assertThat(defaultSnapshotNotifier()).isEqualTo(WhileActive)
+    } finally {
+      System.clearProperty(property)
+    }
+  }
+
+  @Test fun propertyValid() {
+    System.setProperty(property, "External")
+    try {
+      assertThat(defaultSnapshotNotifier()).isEqualTo(External)
+    } finally {
+      System.clearProperty(property)
+    }
+  }
+}

molecule-runtime/src/nonJavaMain/kotlin/app/cash/molecule/platform.kt

@@ -0,0 +1,21 @@
+/*
+ * Copyright (C) 2025 Square, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package app.cash.molecule
+
+@Suppress("NOTHING_TO_INLINE")
+internal actual inline fun defaultSnapshotNotifier(): SnapshotNotifier {
+  return SnapshotNotifier.WhileActive
+}