Enhance Preferences reactivity and test coverage

Refactored ReactiveProperties to use snapshotStateMap for Compose reactivity. Improved PreferencesProvider and watchFile composables with better file watching, override support via system properties, and added documentation. Updated PreferencesKtTest to use temporary files and verify file-to-UI reactivity.

Author: Stefterv

app/src/processing/app/Preferences.kt

@@ -8,24 +8,24 @@ import kotlinx.coroutines.flow.dropWhile
 import kotlinx.coroutines.launch
 import java.io.File
 import java.io.InputStream
-import java.io.OutputStream
 import java.nio.file.*
 import java.util.Properties
 
-
-const val PREFERENCES_FILE_NAME = "preferences.txt"
-const val DEFAULTS_FILE_NAME = "defaults.txt"
-
+/*
+    The ReactiveProperties class extends the standard Java Properties class
+    to provide reactive capabilities using Jetpack Compose's mutableStateMapOf.
+    This allows UI components to automatically update when preference values change.
+*/
 class ReactiveProperties: Properties() {
-    val _stateMap = mutableStateMapOf<String, String>()
+    val snapshotStateMap = mutableStateMapOf<String, String>()
 
     override fun setProperty(key: String, value: String) {
         super.setProperty(key, value)
-        _stateMap[key] = value
+        snapshotStateMap[key] = value
     }
 
     override fun getProperty(key: String): String? {
-        return _stateMap[key] ?: super.getProperty(key)
+        return snapshotStateMap[key] ?: super.getProperty(key)
     }
 
     operator fun get(key: String): String? = getProperty(key)
@@ -34,34 +34,88 @@ class ReactiveProperties: Properties() {
         setProperty(key, value)
     }
 }
+
+/*
+    A CompositionLocal to provide access to the ReactiveProperties instance
+    throughout the composable hierarchy.
+ */
 val LocalPreferences = compositionLocalOf<ReactiveProperties> { error("No preferences provided") }
+
+const val PREFERENCES_FILE_NAME = "preferences.txt"
+const val DEFAULTS_FILE_NAME = "defaults.txt"
+
+/*
+    This composable function sets up a preferences provider that manages application settings.
+    It initializes the preferences from a file, watches for changes to that file, and saves
+    any updates back to the file. It uses a ReactiveProperties class to allow for reactive
+    updates in the UI when preferences change.
+
+    usage:
+    PreferencesProvider {
+        // Your app content here
+    }
+
+    to access preferences:
+    val preferences = LocalPreferences.current
+    val someSetting = preferences["someKey"] ?: "defaultValue"
+    preferences["someKey"] = "newValue"
+
+    This will automatically save to the preferences file and update any UI components
+    that are observing that key.
+
+    to override the preferences file (for testing, etc)
+        System.setProperty("processing.app.preferences.file", "/path/to/your/preferences.txt")
+    to override the debounce time (in milliseconds)
+        System.setProperty("processing.app.preferences.debounce", "200")
+
+ */
 @OptIn(FlowPreview::class)
 @Composable
 fun PreferencesProvider(content: @Composable () -> Unit){
+    val preferencesFileOverride: File? = System.getProperty("processing.app.preferences.file")?.let { File(it) }
+    val preferencesDebounceOverride: Long? = System.getProperty("processing.app.preferences.debounce")?.toLongOrNull()
+
+    // Initialize the platform (if not already done) to ensure we have access to the settings folder
     remember {
         Platform.init()
     }
 
+    // Grab the preferences file, creating it if it doesn't exist
+    // TODO: This functionality should be separated from the `Preferences` class itself
     val settingsFolder = Platform.getSettingsFolder()
-    val preferencesFile = settingsFolder.resolve(PREFERENCES_FILE_NAME)
+    val preferencesFile = preferencesFileOverride ?: settingsFolder.resolve(PREFERENCES_FILE_NAME)
     if(!preferencesFile.exists()){
         preferencesFile.mkdirs()
         preferencesFile.createNewFile()
     }
 
     val update = watchFile(preferencesFile)
-    val properties = remember(preferencesFile, update) { ReactiveProperties().apply {
-        load((ClassLoader.getSystemResourceAsStream(DEFAULTS_FILE_NAME)?: InputStream.nullInputStream()).reader(Charsets.UTF_8))
-        load(preferencesFile.inputStream().reader(Charsets.UTF_8))
-    }}
 
-    val initialState = remember(properties) { properties._stateMap.toMap() }
 
+    val properties = remember(preferencesFile, update) {
+        ReactiveProperties().apply {
+            val defaultsStream = ClassLoader.getSystemResourceAsStream(DEFAULTS_FILE_NAME)
+                ?: InputStream.nullInputStream()
+            load(defaultsStream
+                .reader(Charsets.UTF_8)
+            )
+            load(preferencesFile
+                .inputStream()
+                .reader(Charsets.UTF_8)
+            )
+        }
+    }
+
+    val initialState = remember(properties) { properties.snapshotStateMap.toMap() }
+
+    // Listen for changes to the preferences and save them to file
     LaunchedEffect(properties) {
-        snapshotFlow { properties._stateMap.toMap() }
+        snapshotFlow { properties.snapshotStateMap.toMap() }
             .dropWhile { it == initialState }
-            .debounce(100)
+            .debounce(preferencesDebounceOverride ?: 100)
             .collect {
+
+                // Save the preferences to file, sorted alphabetically
                 preferencesFile.outputStream().use { output ->
                     output.write(
                         properties.entries
@@ -78,24 +132,53 @@ fun PreferencesProvider(content: @Composable () -> Unit){
     }
 
 }
+
+/*
+    This composable function watches a specified file for modifications. When the file is modified,
+    it updates a state variable with the latest WatchEvent. This can be useful for triggering UI updates
+    or other actions in response to changes in the file.
+
+    To watch the file at the fasted speed (for testing) set the following system property:
+        System.setProperty("processing.app.watchfile.forced", "true")
+ */
 @Composable
 fun watchFile(file: File): Any? {
+    val forcedWatch: Boolean = System.getProperty("processing.app.watchfile.forced").toBoolean()
+
     val scope = rememberCoroutineScope()
     var event by remember(file) {  mutableStateOf<WatchEvent<*>?> (null) }
 
     DisposableEffect(file){
         val fileSystem = FileSystems.getDefault()
         val watcher = fileSystem.newWatchService()
+
         var active = true
 
+        // In forced mode we just poll the last modified time of the file
+        // This is not efficient but works better for testing with temp files
+        val toWatch = { file.lastModified() }
+        var state = toWatch()
+
         val path = file.toPath()
         val parent = path.parent
         val key = parent.register(watcher, StandardWatchEventKinds.ENTRY_MODIFY)
         scope.launch(Dispatchers.IO) {
             while (active) {
-                for (modified in key.pollEvents()) {
-                    if (modified.context() != path.fileName) continue
-                    event = modified
+                if(forcedWatch) {
+                    if(toWatch() == state) continue
+                    state = toWatch()
+                    event = object : WatchEvent<Path> {
+                        override fun count(): Int = 1
+                        override fun context(): Path = file.toPath().fileName
+                        override fun kind(): WatchEvent.Kind<Path> = StandardWatchEventKinds.ENTRY_MODIFY
+                        override fun toString(): String = "ForcedEvent(${context()})"
+                    }
+                    continue
+                }else{
+                    for (modified in key.pollEvents()) {
+                        if (modified.context() != path.fileName) continue
+                        event = modified
+                    }
                 }
             }
         }

app/test/processing/app/PreferencesKtTest.kt

@@ -5,14 +5,29 @@ import androidx.compose.material.Text
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.platform.testTag
 import androidx.compose.ui.test.*
+import java.util.Properties
+import kotlin.io.path.createFile
+import kotlin.io.path.createTempDirectory
 import kotlin.test.Test
 
 class PreferencesKtTest{
     @OptIn(ExperimentalTestApi::class)
     @Test
     fun testKeyReactivity() = runComposeUiTest {
+        val directory = createTempDirectory("preferences")
+        val tempPreferences = directory
+            .resolve("preferences.txt")
+            .createFile()
+            .toFile()
+
+        // Set system properties for testing
+        System.setProperty("processing.app.preferences.file", tempPreferences.absolutePath)
+        System.setProperty("processing.app.preferences.debounce", "0")
+        System.setProperty("processing.app.watchfile.forced", "true")
+
         val newValue = (0..Int.MAX_VALUE).random().toString()
-        val testKey = "test.preferences.reactivity.$newValue"
+        val testKey = "test.preferences.reactivity"
+
         setContent {
             PreferencesProvider {
                 val preferences = LocalPreferences.current
@@ -29,6 +44,18 @@ class PreferencesKtTest{
         onNodeWithTag("text").assertTextEquals("default")
         onNodeWithTag("button").performClick()
         onNodeWithTag("text").assertTextEquals(newValue)
-    }
 
+        val preferences = Properties()
+        preferences.load(tempPreferences.inputStream().reader(Charsets.UTF_8))
+
+        // Check if the preference was saved to file
+        assert(preferences[testKey] == newValue)
+
+
+        val nextValue = (0..Int.MAX_VALUE).random().toString()
+        // Overwrite the file to see if the UI updates
+        tempPreferences.writeText("$testKey=${nextValue}")
+
+        onNodeWithTag("text").assertTextEquals(nextValue)
+    }
 }