[Feat] Move to background task

README.md

@@ -126,6 +126,35 @@ val operation = lorraineOperation {
 lorraine.enqueue("user_refresh_chain", operation)
 ```
 
+## 🔄 Migration Guide (0.3.0 to 0.4.0)
+
+Version 0.4.0 introduces a major change in how background tasks are handled on iOS. We've migrated from `NSOperationQueue` to `BGTaskScheduler` for better system integration.
+
+### 1. Register Background Tasks (iOS Only)
+
+You **must** now call `registerTasks()` as early as possible in your app's lifecycle (usually in `application(_:didFinishLaunchingWithOptions:)` or your SwiftUI `App` init).
+
+```kotlin
+// Shared initialization
+val lorraine = initLorraine(context)
+lorraine.registerTasks() // New mandatory step for iOS
+```
+
+### 2. Update Info.plist (iOS Only)
+
+Add the `BGTaskSchedulerPermittedIdentifiers` key to your `Info.plist` and add the Lorraine background task identifier: `io.dot.lorraine.work`.
+
+```xml
+<key>BGTaskSchedulerPermittedIdentifiers</key>
+<array>
+    <string>io.dot.lorraine.work</string>
+</array>
+```
+
+Also, ensure **Background Modes** (Background fetch and Background processing) are enabled in your project's Capabilities.
+
+---
+
 ## 🔍 Observing Work
 
 You can monitor the status of your tasks in real-time:

lorraine/lorraine.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |spec|
     spec.name                     = 'lorraine'
-    spec.version                  = '0.2.2'
+    spec.version                  = '0.3.0'
     spec.homepage                 = 'NO_HOMEPAGE'
     spec.source                   = { :http=> ''}
     spec.authors                  = ''

lorraine/src/commonMain/kotlin/io/dot/lorraine/Lorraine.kt

@@ -10,18 +10,14 @@ import io.dot.lorraine.dsl.lorraineOperation
 import io.dot.lorraine.dsl.lorraineRequest
 import io.dot.lorraine.models.ExistingLorrainePolicy
 import io.dot.lorraine.models.LorraineInfo
-import kotlinx.coroutines.flow.Flow
 import kotlin.uuid.ExperimentalUuidApi
 import kotlin.uuid.Uuid
+import kotlinx.coroutines.flow.Flow
 
 internal const val LORRAINE_DATABASE = "lorraine.db"
 
-/**
- * Instance of [Lorraine], to enqueue lorraine's workers
- */
-class Lorraine private constructor(
-    private val platform: Platform
-) {
+/** Instance of [Lorraine], to enqueue lorraine's workers */
+class Lorraine private constructor(private val platform: Platform) {
 
     /**
      * Enqueue a [LorraineRequest]
@@ -30,16 +26,8 @@ class Lorraine private constructor(
      * @param type to enqueue
      * @param request, actual request
      */
-    suspend fun enqueue(
-        queueId: String,
-        type: ExistingLorrainePolicy,
-        request: LorraineRequest
-    ) {
-        platform.enqueue(
-            queueId = queueId,
-            type = type,
-            lorraineRequest = request
-        )
+    suspend fun enqueue(queueId: String, type: ExistingLorrainePolicy, request: LorraineRequest) {
+        platform.enqueue(queueId = queueId, type = type, lorraineRequest = request)
     }
 
     /**
@@ -48,14 +36,8 @@ class Lorraine private constructor(
      * @param uniqueId for the queue
      * @param operation to enqueue
      */
-    suspend fun enqueue(
-        queueId: String,
-        operation: LorraineOperation
-    ) {
-        platform.enqueue(
-            queueId = queueId,
-            operation = operation
-        )
+    suspend fun enqueue(queueId: String, operation: LorraineOperation) {
+        platform.enqueue(queueId = queueId, operation = operation)
     }
 
     suspend fun cancelWorkById(uuid: Uuid) {
@@ -82,36 +64,29 @@ class Lorraine private constructor(
         return platform.listenLorrainesInfo()
     }
 
+    /**
+     * Register background tasks. Required on iOS to register task identifiers with BGTaskScheduler.
+     */
+    fun registerTasks() {
+        platform.registerTasks()
+    }
+
     companion object {
 
-        internal fun create(
-            platform: Platform
-        ): Lorraine {
+        internal fun create(platform: Platform): Lorraine {
             return Lorraine(platform = platform)
         }
-
     }
-
 }
 
 suspend fun Lorraine.enqueue(
-    queueId: String,
-    type: ExistingLorrainePolicy,
-    block: LorraineRequestDefinition.() -> Unit
+        queueId: String,
+        type: ExistingLorrainePolicy,
+        block: LorraineRequestDefinition.() -> Unit
 ) {
-    enqueue(
-        queueId = queueId,
-        type = type,
-        request = lorraineRequest(block)
-    )
+    enqueue(queueId = queueId, type = type, request = lorraineRequest(block))
 }
 
-suspend fun Lorraine.enqueue(
-    queueId: String,
-    block: LorraineOperationDefinition.() -> Unit
-) {
-    enqueue(
-        queueId = queueId,
-        operation = lorraineOperation(block)
-    )
-}
+suspend fun Lorraine.enqueue(queueId: String, block: LorraineOperationDefinition.() -> Unit) {
+    enqueue(queueId = queueId, operation = lorraineOperation(block))
+}

lorraine/src/commonMain/kotlin/io/dot/lorraine/Platform.kt

@@ -36,4 +36,6 @@ internal interface Platform {
 
     fun listenLorrainesInfo(): Flow<List<LorraineInfo>>
 
+    fun registerTasks()
+
 }