Line data    Source code

       1              : part of '../worker.dart';
       2              : 
       3              : /// Custom native worker for user-defined implementations.
       4              : ///
       5              : /// Allows users to implement their own native workers (in Kotlin/Swift)
       6              : /// without modifying the plugin source code. This is the extensibility
       7              : /// escape hatch for advanced use cases not covered by built-in workers.
       8              : ///
       9              : /// ## Prerequisites
      10              : ///
      11              : /// **You must implement the native worker first:**
      12              : ///
      13              : /// **Android (Kotlin):**
      14              : /// ```kotlin
      15              : /// package com.myapp.workers
      16              : ///
      17              : /// import dev.brewkits.kmpworkmanager.background.domain.AndroidWorker
      18              : ///
      19              : /// class ImageCompressWorker : AndroidWorker {
      20              : ///     override suspend fun doWork(input: String?): Boolean {
      21              : ///         // Parse input JSON
      22              : ///         val config = parseJson(input)
      23              : ///         val imagePath = config["imagePath"] as String
      24              : ///
      25              : ///         // Compress image (native code)
      26              : ///         compressImage(imagePath, quality = 85)
      27              : ///
      28              : ///         return true
      29              : ///     }
      30              : /// }
      31              : /// ```
      32              : ///
      33              : /// **iOS (Swift):**
      34              : /// ```swift
      35              : /// import Foundation
      36              : ///
      37              : /// class ImageCompressWorker: IosWorker {
      38              : ///     func doWork(input: String?) async throws -> Bool {
      39              : ///         // Parse input JSON
      40              : ///         let config = parseJson(input)
      41              : ///         let imagePath = config["imagePath"]
      42              : ///
      43              : ///         // Compress image (native code)
      44              : ///         compressImage(imagePath, quality: 85)
      45              : ///
      46              : ///         return true
      47              : ///     }
      48              : /// }
      49              : /// ```
      50              : ///
      51              : /// ## Registration
      52              : ///
      53              : /// **Android:** Register in `MainActivity.kt` before `initialize()`:
      54              : /// ```kotlin
      55              : /// NativeWorkManager.registerWorkerFactory { className ->
      56              : ///     when (className) {
      57              : ///         "ImageCompressWorker" -> ImageCompressWorker()
      58              : ///         else -> null
      59              : ///     }
      60              : /// }
      61              : /// ```
      62              : ///
      63              : /// **iOS:** Register in `AppDelegate.swift`:
      64              : /// ```swift
      65              : /// NativeWorkManager.registerWorker(
      66              : ///     className: "ImageCompressWorker",
      67              : ///     factory: { ImageCompressWorker() }
      68              : /// )
      69              : /// ```
      70              : ///
      71              : /// ## Dart Usage
      72              : ///
      73              : /// ```dart
      74              : /// await NativeWorkManager.enqueue(
      75              : ///   taskId: 'compress-photo',
      76              : ///   trigger: TaskTrigger.oneTime(),
      77              : ///   worker: NativeWorker.custom(
      78              : ///     className: 'ImageCompressWorker',
      79              : ///     input: {
      80              : ///       'imagePath': '/storage/photo.jpg',
      81              : ///       'quality': 85,
      82              : ///       'outputPath': '/storage/compressed.jpg',
      83              : ///     },
      84              : ///   ),
      85              : /// );
      86              : /// ```
      87              : ///
      88              : /// ## Parameters
      89              : ///
      90              : /// **[className]** *(required)* - The worker class name.
      91              : /// - Must match the class name you implemented in Kotlin/Swift
      92              : /// - Must be registered before calling enqueue
      93              : /// - Case-sensitive exact match
      94              : ///
      95              : /// **[input]** *(optional)* - Configuration data for the worker.
      96              : /// - Will be JSON encoded and passed to `doWork(input)`
      97              : /// - Can contain any JSON-serializable data
      98              : ///
      99              : /// ## When to Use
     100              : ///
     101              : /// ✅ **Use CustomNativeWorker when:**
     102              : /// - You need native processing not covered by built-in workers
     103              : /// - Image/video compression, encoding, encryption
     104              : /// - Native database operations (Room, Core Data)
     105              : /// - Platform-specific APIs (camera, sensors, etc.)
     106              : /// - You want maximum performance (native execution)
     107              : ///
     108              : /// ❌ **Don't use CustomNativeWorker when:**
     109              : /// - Built-in workers already cover your use case
     110              : /// - Simple HTTP operations → Use built-in HTTP workers
     111              : /// - You need Dart/Flutter APIs → Use `DartWorker` instead
     112              : ///
     113              : /// ## Performance
     114              : ///
     115              : /// - RAM: ~2-5MB (same as built-in native workers)
     116              : /// - Startup: <50ms (no Flutter Engine)
     117              : /// - Same benefits as built-in native workers
     118              : ///
     119              : /// ## See Also
     120              : ///
     121              : /// - [DartWorker] - For Dart-based custom logic
     122              : /// - Built-in workers: [NativeWorker.httpRequest], [NativeWorker.httpUpload],
     123              : ///   [NativeWorker.httpDownload], [NativeWorker.httpSync]
     124            2 : Worker _buildCustom({
     125              :   required String className,
     126              :   Map<String, dynamic>? input,
     127              : }) {
     128            2 :   if (className.isEmpty) {
     129            1 :     throw ArgumentError(
     130              :       'className cannot be empty.\n'
     131              :       'Provide the name of your custom worker class (e.g., "ImageCompressWorker")',
     132              :     );
     133              :   }
     134              : 
     135            2 :   return CustomNativeWorker(className: className, input: input);
     136              : }