feat(state): Add SafeBoxGlobalStateObserver and closeWhenIdle support (#14)

Author: harrytmthy

safebox/src/androidTest/java/com/harrytmthy/safebox/storage/SafeBoxBlobStoreTest.kt

@@ -22,7 +22,11 @@ import androidx.test.ext.junit.runners.AndroidJUnit4
 import com.harrytmthy.safebox.extensions.toBytes
 import com.harrytmthy.safebox.state.SafeBoxState
 import com.harrytmthy.safebox.state.SafeBoxStateListener
+import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.joinAll
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.test.UnconfinedTestDispatcher
 import kotlinx.coroutines.test.runTest
 import org.junit.After
@@ -218,19 +222,65 @@ class SafeBoxBlobStoreTest {
     }
 
     @Test
-    fun write_shouldEmitWritingAndIdleStates() = runTest {
-        val key = "alpha".toByteArray().toBytes()
-        val value = "123".toByteArray()
-
-        blobStore.write(key, value)
-
-        assertEquals(listOf(SafeBoxState.WRITING, SafeBoxState.IDLE), observedStates)
+    fun write_shouldEmitWritingAndIdleStates() = runBlocking {
+        buildList {
+            repeat(10) {
+                add(
+                    launch(Dispatchers.Default) {
+                        blobStore.write("alpha".toByteArray().toBytes(), "123".toByteArray())
+                    },
+                )
+            }
+        }.joinAll()
+
+        val expected = listOf(
+            SafeBoxState.STARTING,
+            SafeBoxState.IDLE,
+            SafeBoxState.WRITING,
+            SafeBoxState.IDLE,
+        )
+        assertEquals(expected, observedStates)
     }
 
     @Test
     fun close_shouldEmitClosedState() {
         blobStore.close()
 
-        assertEquals(SafeBoxState.CLOSED, observedStates.last())
+        val expected = listOf(
+            SafeBoxState.STARTING,
+            SafeBoxState.IDLE,
+            SafeBoxState.CLOSED,
+        )
+        assertEquals(expected, observedStates)
+    }
+
+    @Test
+    fun closeWhenIdle_shouldWaitUntilWritesAreDone() = runTest {
+        buildList {
+            repeat(5) {
+                add(
+                    launch(Dispatchers.Default) {
+                        blobStore.write("alpha".toByteArray().toBytes(), "123".toByteArray())
+                    },
+                )
+            }
+            add(launch(Dispatchers.Default) { blobStore.closeWhenIdle() })
+            repeat(5) {
+                add(
+                    launch(Dispatchers.Default) {
+                        blobStore.write("alpha".toByteArray().toBytes(), "123".toByteArray())
+                    },
+                )
+            }
+        }.joinAll()
+
+        val expected = listOf(
+            SafeBoxState.STARTING,
+            SafeBoxState.IDLE,
+            SafeBoxState.WRITING,
+            SafeBoxState.IDLE,
+            SafeBoxState.CLOSED,
+        )
+        assertEquals(expected, observedStates)
     }
 }

safebox/src/main/java/com/harrytmthy/safebox/SafeBox.kt

@@ -160,13 +160,32 @@ public class SafeBox private constructor(
      * ⚠️ Once closed, this instance becomes *permanently unusable*. Any further access will fail.
      *
      * ⚠️ Only use this method when you're certain that no writes are in progress.
+     *
      * Closing during an active write can result in data corruption or incomplete persistence.
      */
     public fun close() {
         SafeBoxBlobFileRegistry.unregister(blobStore.getFileName())
         blobStore.close()
     }
 
+    /**
+     * Closes the underlying file channel only after all pending writes have completed.
+     * Also unregisters the file from [SafeBoxBlobFileRegistry], allowing a new SafeBox
+     * instance to be created with the same filename.
+     *
+     * ⚠️ Once closed, this instance becomes *permanently unusable*. Any further access will fail.
+     *
+     * ✅ This is the recommended way to dispose of SafeBox in async environments.
+     *
+     * Internally, this launches a coroutine on [safeBoxScope] to wait until the SafeBox
+     * becomes idle before releasing resources.
+     */
+    public fun closeWhenIdle() {
+        safeBoxScope.launch(ioDispatcher) {
+            blobStore.closeWhenIdle()
+        }
+    }
+
     override fun getAll(): Map<String, Any?> {
         val encryptedEntries = blobStore.getAll()
         val decryptedEntries = HashMap<String, Any?>(encryptedEntries.size, 1f)

safebox/src/main/java/com/harrytmthy/safebox/registry/SafeBoxBlobFileRegistry.kt

@@ -17,6 +17,7 @@
 package com.harrytmthy.safebox.registry
 
 import com.harrytmthy.safebox.SafeBox
+import com.harrytmthy.safebox.state.SafeBoxGlobalStateObserver
 import java.util.Collections
 import java.util.concurrent.ConcurrentHashMap
 
@@ -27,7 +28,7 @@ import java.util.concurrent.ConcurrentHashMap
  * This ensures thread safety and prevents corruption due to concurrent `FileChannel` access.
  *
  * This registry is internal-only and not intended for external observation.
- * Please use [SafeBoxStateObserver] to listen for state changes.
+ * Please use [SafeBoxGlobalStateObserver] to listen for state changes.
  */
 internal object SafeBoxBlobFileRegistry {
 

safebox/src/main/java/com/harrytmthy/safebox/state/SafeBoxGlobalStateObserver.kt

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2025 Harry Timothy Tumalewa
+ *
+ * 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
+ *
+ *     https://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 com.harrytmthy.safebox.state
+
+import com.harrytmthy.safebox.state.SafeBoxGlobalStateObserver.updateState
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.CopyOnWriteArraySet
+
+/**
+ * Public observer interface for monitoring SafeBox state changes.
+ *
+ * Allows clients to observe SafeBox's lifecycle state transitions for a given file name,
+ * enabling safer orchestration in multi-screen or asynchronous apps.
+ */
+public object SafeBoxGlobalStateObserver {
+
+    private val stateHolder = ConcurrentHashMap<String, SafeBoxState>()
+
+    private val listeners = ConcurrentHashMap<String, CopyOnWriteArraySet<SafeBoxStateListener>>()
+
+    /**
+     * Returns the most recently known state of the SafeBox associated with the given file name.
+     *
+     * This value reflects the latest emitted state via [updateState], even if no active listener
+     * was registered at the time of the change.
+     *
+     * @param fileName The file name being observed.
+     * @return The last known [SafeBoxState], or `null` if the file name has never been registered.
+     */
+    @JvmStatic
+    public fun getCurrentState(fileName: String): SafeBoxState? =
+        stateHolder[fileName]
+
+    /**
+     * Adds a listener for the given SafeBox file name. The listener will immediately receive
+     * the current state (if any), followed by all future updates.
+     *
+     * @param fileName The name of the SafeBox file to observe.
+     * @param listener The listener to be notified of state changes.
+     */
+    @JvmStatic
+    public fun addListener(fileName: String, listener: SafeBoxStateListener) {
+        listeners.getOrPut(fileName, defaultValue = { CopyOnWriteArraySet() }).add(listener)
+        stateHolder[fileName]?.let(listener::onStateChanged)
+    }
+
+    /**
+     * Removes a previously registered listener for a specific file.
+     *
+     * @param fileName The file name being observed.
+     * @param listener The listener to remove.
+     */
+    @JvmStatic
+    public fun removeListener(fileName: String, listener: SafeBoxStateListener) {
+        listeners[fileName]?.remove(listener)
+    }
+
+    /**
+     * Emits a new state for the given file name, updating internal records
+     * and notifying all registered listeners for that file.
+     *
+     * This method is called internally by SafeBox and SafeBoxBlobFileRegistry
+     * to reflect changes in the instance's lifecycle.
+     *
+     * @param fileName The file name whose state has changed.
+     * @param newState The new [SafeBoxState] to emit.
+     */
+    internal fun updateState(fileName: String, newState: SafeBoxState) {
+        stateHolder[fileName] = newState
+        listeners[fileName]?.forEach { it.onStateChanged(newState) }
+    }
+}

safebox/src/main/java/com/harrytmthy/safebox/state/SafeBoxState.kt

@@ -29,20 +29,29 @@ import com.harrytmthy.safebox.SafeBox
 public enum class SafeBoxState {
 
     /**
-     * Indicates that SafeBox is idle and not currently writing to disk.
-     * This is the default resting state.
+     * Indicates that SafeBox has been successfully created and currently loading persisted data
+     * from disk into memory.
+     *
+     * During this state, SafeBox is not yet ready to serve read or write operations.
+     * Any read/write call will be suspended until the state transitions to [IDLE].
+     */
+    STARTING,
+
+    /**
+     * Indicates that SafeBox is ready and currently idle, with no active write operations.
+     * This is the default state after initialization completes and between writes.
      */
     IDLE,
 
     /**
-     * Indicates that SafeBox is performing a write operation.
+     * Indicates that SafeBox is currently writing data to disk.
      * Avoid closing or deleting the SafeBox during this time.
      */
     WRITING,
 
     /**
      * Indicates that SafeBox has been closed and is no longer usable.
-     * Once closed, a SafeBox instance cannot be reused.
+     * To access the same file again, a new SafeBox instance must be created.
      */
     CLOSED,
 }

safebox/src/main/java/com/harrytmthy/safebox/storage/SafeBoxBlobStore.kt

@@ -21,12 +21,22 @@ import android.util.Log
 import androidx.annotation.VisibleForTesting
 import com.harrytmthy.safebox.extensions.safeBoxScope
 import com.harrytmthy.safebox.extensions.toBytes
+import com.harrytmthy.safebox.state.SafeBoxGlobalStateObserver
+import com.harrytmthy.safebox.state.SafeBoxGlobalStateObserver.getCurrentState
 import com.harrytmthy.safebox.state.SafeBoxState
+import com.harrytmthy.safebox.state.SafeBoxState.CLOSED
+import com.harrytmthy.safebox.state.SafeBoxState.IDLE
+import com.harrytmthy.safebox.state.SafeBoxState.STARTING
+import com.harrytmthy.safebox.state.SafeBoxState.WRITING
 import com.harrytmthy.safebox.state.SafeBoxStateListener
 import com.harrytmthy.safebox.strategy.ValueFallbackStrategy
 import com.harrytmthy.safebox.strategy.ValueFallbackStrategy.ERROR
 import com.harrytmthy.safebox.strategy.ValueFallbackStrategy.WARN
 import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.dropWhile
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.flow.update
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
@@ -66,12 +76,14 @@ internal class SafeBoxBlobStore private constructor(
 
     private val writeMutex = Mutex()
 
+    private val pendingWriteCount = MutableStateFlow(0)
+
     private val nextWritePosition: Int
         get() = entryMetas.values.lastOrNull()?.run { offset + size } ?: 0
 
     init {
         safeBoxScope.launch(ioDispatcher) {
-            writeMutex.withLock {
+            writeMutex.withLockAndStateUpdates(initialState = STARTING) {
                 var offset = 0
                 while (offset + HEADER_SIZE <= buffer.capacity()) {
                     buffer.position(offset)
@@ -199,7 +211,17 @@ internal class SafeBoxBlobStore private constructor(
      */
     internal fun close() {
         channel.close()
-        stateListener?.onStateChanged(SafeBoxState.CLOSED)
+        stateListener?.onStateChanged(CLOSED)
+        SafeBoxGlobalStateObserver.updateState(getFileName(), CLOSED)
+    }
+
+    internal suspend fun closeWhenIdle() {
+        if (pendingWriteCount.value == 0 || getCurrentState(getFileName()) == STARTING) {
+            close()
+            return
+        }
+        pendingWriteCount.dropWhile { it != 0 }.first()
+        close()
     }
 
     private fun writeAtOffset(
@@ -285,18 +307,28 @@ internal class SafeBoxBlobStore private constructor(
     }
 
     /**
-     * Wraps the given [action] with mutex locking and emits SafeBox state transitions.
-     *
-     * This ensures that any critical write operation is surrounded by `WRITING` and `IDLE` events,
-     * which helps external listeners track write progress.
+     * Wraps the given [action] with a mutex lock and emits corresponding state transitions.
+     * This allows external listeners to track internal state changes.
      */
-    private suspend inline fun <T> Mutex.withLockAndStateUpdates(crossinline action: () -> T): T =
-        withLock {
-            stateListener?.onStateChanged(SafeBoxState.WRITING)
+    private suspend inline fun <T> Mutex.withLockAndStateUpdates(
+        initialState: SafeBoxState = WRITING,
+        crossinline action: () -> T,
+    ): T {
+        pendingWriteCount.update { it + 1 }
+        return withLock {
+            if (getCurrentState(getFileName()) != initialState) {
+                stateListener?.onStateChanged(initialState)
+                SafeBoxGlobalStateObserver.updateState(getFileName(), initialState)
+            }
             val result = action()
-            stateListener?.onStateChanged(SafeBoxState.IDLE)
+            pendingWriteCount.update { it - 1 }
+            if (pendingWriteCount.value == 0) {
+                stateListener?.onStateChanged(IDLE)
+                SafeBoxGlobalStateObserver.updateState(getFileName(), IDLE)
+            }
             result
         }
+    }
 
     @VisibleForTesting
     internal data class EntryMeta(val offset: Int, val size: Int)