react-native-nitro-unzip 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Isaac Rowntree
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# react-native-nitro-unzip
+
+High-performance ZIP extraction for React Native, powered by [Nitro Modules](https://nitro.margelo.com/).
+
+- **iOS**: SSZipArchive (C-based libz) — ~500 files/sec
+- **Android**: Optimized ZipInputStream with 64KB buffers — ~474 files/sec
+- **Zero bridge overhead** for progress callbacks (JSI-based)
+- **Proper object instances** — each extraction is an `UnzipTask` you can observe and cancel
+- **Concurrent extractions** supported out of the box
+- **iOS background task** management for continued extraction when app is backgrounded
+
+## Installation
+
+```bash
+npm install react-native-nitro-unzip react-native-nitro-modules
+cd ios && pod install
+```
+
+## Usage
+
+```typescript
+import { getUnzip } from 'react-native-nitro-unzip'
+
+const unzip = getUnzip()
+const task = unzip.extract('/path/to/archive.zip', '/path/to/output')
+
+// Track progress
+task.onProgress((p) => {
+  console.log(`${(p.progress * 100).toFixed(0)}% — ${p.extractedFiles}/${p.totalFiles} files`)
+  console.log(`Speed: ${p.speed.toFixed(0)} files/sec`)
+})
+
+// Await result
+const result = await task.await()
+console.log(`Extracted ${result.extractedFiles} files in ${result.duration}ms`)
+
+// Or cancel
+task.cancel()
+```
+
+## API
+
+### `getUnzip(): Unzip`
+
+Creates an `Unzip` factory instance.
+
+### `Unzip.extract(zipPath, destinationPath): UnzipTask`
+
+Starts extracting a ZIP archive. Returns an `UnzipTask` instance immediately.
+
+- `zipPath` — absolute path to the ZIP file (`file://` URIs accepted)
+- `destinationPath` — absolute path to extract into (created if missing)
+
+### `UnzipTask`
+
+| Property/Method | Type | Description |
+|---|---|---|
+| `taskId` | `string` | Unique identifier for this extraction |
+| `onProgress(callback)` | `(progress: UnzipProgress) => void` | Register a progress callback (throttled to ~1/sec) |
+| `cancel()` | `void` | Cancel this extraction |
+| `await()` | `Promise<UnzipResult>` | Await the extraction result |
+
+### `UnzipProgress`
+
+| Field | Type | Description |
+|---|---|---|
+| `extractedFiles` | `number` | Files extracted so far |
+| `totalFiles` | `number` | Total files in archive |
+| `progress` | `number` | 0.0 to 1.0 |
+| `speed` | `number` | Files per second |
+| `processedBytes` | `number` | Bytes processed |
+
+### `UnzipResult`
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | `boolean` | Whether extraction completed |
+| `extractedFiles` | `number` | Total files extracted |
+| `duration` | `number` | Duration in milliseconds |
+| `averageSpeed` | `number` | Average files per second |
+| `totalBytes` | `number` | Total bytes extracted |
+
+## Performance
+
+Benchmarked on a 350MB archive with 10,432 small files (map tiles):
+
+| Platform | Speed | Time |
+|---|---|---|
+| iOS (iPhone) | ~500 files/sec | ~20s |
+| Android | ~474 files/sec | ~22s |
+
+### Why it's fast
+
+- **iOS**: SSZipArchive uses C-based libz decompression with streaming extraction
+- **Android**: 64KB I/O buffers (8x default), batch directory creation, buffered streams
+- **Both**: Progress callbacks go through JSI (no bridge serialization), throttled to 1/sec
+
+## Requirements
+
+- React Native 0.75+
+- Nitro Modules 0.34+
+- iOS 13+
+- Android SDK 21+
+
+## License
+
+MIT

package/android/CMakeLists.txt

@@ -0,0 +1,16 @@
+cmake_minimum_required(VERSION 3.9.0)
+project(NitroUnzip)
+
+# C++ 20 required by Nitro
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Define the C++ library
+add_library(
+  NitroUnzip
+  SHARED
+  src/main/cpp/cpp-adapter.cpp
+)
+
+# Include Nitrogen generated sources + link NitroModules
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/NitroUnzip+autolinking.cmake)

package/android/build.gradle

@@ -0,0 +1,70 @@
+buildscript {
+  ext.safeExtGet = {prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+  }
+
+  repositories {
+    mavenCentral()
+    google()
+  }
+  dependencies {
+    classpath("com.android.tools.build:gradle:8.2.1")
+    classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.25")
+  }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+// Nitrogen autolinking — adds generated Kotlin sources
+apply from: '../nitrogen/generated/android/NitroUnzip+autolinking.gradle'
+
+android {
+  namespace "com.margelo.nitro.unzip"
+  compileSdkVersion safeExtGet("compileSdkVersion", 35)
+
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 21)
+    targetSdkVersion safeExtGet("targetSdkVersion", 35)
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-O2 -frtti -fexceptions -Wall -fstack-protector-all"
+        abiFilters "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
+      }
+    }
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+  kotlinOptions {
+    jvmTarget = '17'
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += ['src/main/java']
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android:+"
+  implementation "com.facebook.react:react-native:+"
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3"
+  // zip4j — needed for password-protected zip/unzip (java.util.zip has no password API)
+  implementation "net.lingala.zip4j:zip4j:2.11.5"
+}

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,6 @@
+#include <jni.h>
+#include "NitroUnzipOnLoad.hpp"
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return margelo::nitro::unzip::initialize(vm);
+}

package/android/src/main/java/com/margelo/nitro/unzip/HybridUnzip.kt

@@ -0,0 +1,29 @@
+package com.margelo.nitro.unzip
+
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+
+/**
+ * Factory HybridObject that creates extraction and compression tasks.
+ */
+@DoNotStrip
+@Keep
+class HybridUnzip : HybridUnzipSpec() {
+  override val memorySize: Long = 0L
+
+  override fun extract(zipPath: String, destinationPath: String): HybridUnzipTaskSpec {
+    return HybridUnzipTask(zipPath, destinationPath)
+  }
+
+  override fun extractWithPassword(zipPath: String, destinationPath: String, password: String): HybridUnzipTaskSpec {
+    return HybridUnzipTask(zipPath, destinationPath, password)
+  }
+
+  override fun zip(sourcePath: String, destinationZipPath: String): HybridZipTaskSpec {
+    return HybridZipTask(sourcePath, destinationZipPath)
+  }
+
+  override fun zipWithPassword(sourcePath: String, destinationZipPath: String, password: String): HybridZipTaskSpec {
+    return HybridZipTask(sourcePath, destinationZipPath, password)
+  }
+}

package/android/src/main/java/com/margelo/nitro/unzip/HybridUnzipTask.kt

@@ -0,0 +1,256 @@
+package com.margelo.nitro.unzip
+
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.core.Promise
+import kotlinx.coroutines.*
+import java.io.BufferedInputStream
+import java.io.BufferedOutputStream
+import java.io.File
+import java.io.FileOutputStream
+import java.util.zip.ZipInputStream
+
+/**
+ * A single extraction operation as a proper HybridObject instance.
+ *
+ * Performance (350MB archive, 10k+ files):
+ * - Speed: ~474 files/second
+ * - Optimizations: 64KB buffers, batch directory creation, buffered streams
+ * - Coroutine-based with cooperative cancellation
+ *
+ * When a password is provided, uses zip4j for decryption. Otherwise uses
+ * the fast built-in ZipInputStream path (no extra dependency overhead).
+ */
+@DoNotStrip
+@Keep
+class HybridUnzipTask(
+  private val zipPath: String,
+  private val destinationPath: String,
+  private val password: String? = null
+) : HybridUnzipTaskSpec() {
+
+  override val memorySize: Long = 0L
+
+  override val taskId: String = "unzip_${System.nanoTime()}_${(Math.random() * 1e9).toLong()}"
+
+  private var progressCallback: ((UnzipProgress) -> Unit)? = null
+  private var extractionJob: Job? = null
+
+  @Volatile
+  private var shouldCancel = false
+
+  override fun onProgress(callback: (progress: UnzipProgress) -> Unit) {
+    progressCallback = callback
+  }
+
+  override fun cancel() {
+    shouldCancel = true
+    extractionJob?.cancel()
+  }
+
+  override fun await(): Promise<UnzipResult> {
+    return Promise.async { resolve, reject ->
+      try {
+        val result = if (password != null) extractWithPassword() else extract()
+        resolve(result)
+      } catch (e: CancellationException) {
+        reject(Exception("Extraction cancelled"))
+      } catch (e: Exception) {
+        reject(e)
+      }
+    }
+  }
+
+  /**
+   * Fast path — built-in ZipInputStream, no password support.
+   */
+  private suspend fun extract(): UnzipResult = withContext(Dispatchers.IO) {
+    extractionJob = coroutineContext[Job]
+
+    val startTime = System.currentTimeMillis()
+
+    val cleanZip = zipPath.replace("file://", "")
+    val cleanDest = destinationPath.replace("file://", "")
+
+    val destDir = File(cleanDest)
+    if (!destDir.exists()) {
+      destDir.mkdirs()
+    }
+
+    val sourceFile = File(cleanZip)
+    if (!sourceFile.exists()) {
+      throw Exception("Source ZIP file not found: $cleanZip")
+    }
+
+    // --- Pass 1: collect directories ---
+    val directoriesToCreate = hashSetOf<String>()
+    val fileEntries = mutableListOf<String>()
+
+    ZipInputStream(BufferedInputStream(sourceFile.inputStream(), BUFFER_SIZE)).use { zis ->
+      var entry = zis.nextEntry
+      while (entry != null) {
+        if (entry.isDirectory) {
+          directoriesToCreate.add(entry.name)
+        } else {
+          fileEntries.add(entry.name)
+          val parent = File(entry.name).parent
+          if (parent != null) {
+            directoriesToCreate.add(parent)
+          }
+        }
+        entry = zis.nextEntry
+      }
+    }
+
+    // Batch create all directories
+    directoriesToCreate.sorted().forEach { dirPath ->
+      File(destDir, dirPath).mkdirs()
+    }
+
+    // --- Pass 2: extract files ---
+    var extractedCount = 0
+    var lastProgressUpdate = System.currentTimeMillis()
+    val totalEntries = fileEntries.size
+
+    ZipInputStream(BufferedInputStream(sourceFile.inputStream(), BUFFER_SIZE)).use { zis ->
+      var entry = zis.nextEntry
+
+      while (entry != null && isActive && !shouldCancel) {
+        if (!entry.isDirectory) {
+          val entryFile = File(destDir, entry.name)
+
+          BufferedOutputStream(FileOutputStream(entryFile), BUFFER_SIZE).use { output ->
+            val buffer = ByteArray(BUFFER_SIZE)
+            var bytesRead: Int
+            while (zis.read(buffer).also { bytesRead = it } != -1) {
+              output.write(buffer, 0, bytesRead)
+            }
+          }
+
+          extractedCount++
+
+          // Throttle progress updates
+          val now = System.currentTimeMillis()
+          val shouldUpdate = (now - lastProgressUpdate >= PROGRESS_THROTTLE_MS)
+            || (extractedCount == totalEntries)
+            || (extractedCount == 1)
+
+          if (shouldUpdate) {
+            val progress = if (totalEntries > 0) extractedCount.toDouble() / totalEntries else 0.0
+            val elapsed = (now - startTime) / 1000.0
+            val speed = if (elapsed > 0) extractedCount / elapsed else 0.0
+
+            progressCallback?.invoke(
+              UnzipProgress(
+                extractedFiles = extractedCount.toDouble(),
+                totalFiles = totalEntries.toDouble(),
+                progress = progress,
+                speed = speed,
+                processedBytes = 0.0
+              )
+            )
+            lastProgressUpdate = now
+          }
+        }
+
+        entry = zis.nextEntry
+      }
+    }
+
+    if (shouldCancel) {
+      throw CancellationException("Extraction cancelled")
+    }
+
+    val durationMs = (System.currentTimeMillis() - startTime).toDouble()
+    val avgSpeed = if (durationMs > 0) extractedCount / (durationMs / 1000.0) else 0.0
+
+    UnzipResult(
+      success = true,
+      extractedFiles = extractedCount.toDouble(),
+      duration = durationMs,
+      averageSpeed = avgSpeed,
+      totalBytes = 0.0
+    )
+  }
+
+  /**
+   * Password-protected extraction using zip4j.
+   */
+  private suspend fun extractWithPassword(): UnzipResult = withContext(Dispatchers.IO) {
+    extractionJob = coroutineContext[Job]
+
+    val startTime = System.currentTimeMillis()
+
+    val cleanZip = zipPath.replace("file://", "")
+    val cleanDest = destinationPath.replace("file://", "")
+
+    val destDir = File(cleanDest)
+    if (!destDir.exists()) {
+      destDir.mkdirs()
+    }
+
+    val sourceFile = File(cleanZip)
+    if (!sourceFile.exists()) {
+      throw Exception("Source ZIP file not found: $cleanZip")
+    }
+
+    val zipFile = net.lingala.zip4j.ZipFile(sourceFile)
+    zipFile.setPassword(password!!.toCharArray())
+
+    val fileHeaders = zipFile.fileHeaders
+    val totalEntries = fileHeaders.size
+    var extractedCount = 0
+    var lastProgressUpdate = System.currentTimeMillis()
+
+    for (header in fileHeaders) {
+      if (!isActive || shouldCancel) break
+
+      if (!header.isDirectory) {
+        zipFile.extractFile(header, cleanDest)
+        extractedCount++
+
+        val now = System.currentTimeMillis()
+        val shouldUpdate = (now - lastProgressUpdate >= PROGRESS_THROTTLE_MS)
+          || (extractedCount == totalEntries)
+          || (extractedCount == 1)
+
+        if (shouldUpdate) {
+          val progress = if (totalEntries > 0) extractedCount.toDouble() / totalEntries else 0.0
+          val elapsed = (now - startTime) / 1000.0
+          val speed = if (elapsed > 0) extractedCount / elapsed else 0.0
+
+          progressCallback?.invoke(
+            UnzipProgress(
+              extractedFiles = extractedCount.toDouble(),
+              totalFiles = totalEntries.toDouble(),
+              progress = progress,
+              speed = speed,
+              processedBytes = 0.0
+            )
+          )
+          lastProgressUpdate = now
+        }
+      }
+    }
+
+    if (shouldCancel) {
+      throw CancellationException("Extraction cancelled")
+    }
+
+    val durationMs = (System.currentTimeMillis() - startTime).toDouble()
+    val avgSpeed = if (durationMs > 0) extractedCount / (durationMs / 1000.0) else 0.0
+
+    UnzipResult(
+      success = true,
+      extractedFiles = extractedCount.toDouble(),
+      duration = durationMs,
+      averageSpeed = avgSpeed,
+      totalBytes = 0.0
+    )
+  }
+
+  companion object {
+    private const val BUFFER_SIZE = 65536
+    private const val PROGRESS_THROTTLE_MS = 1000L
+  }
+}

package/android/src/main/java/com/margelo/nitro/unzip/HybridZipTask.kt

@@ -0,0 +1,157 @@
+package com.margelo.nitro.unzip
+
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.core.Promise
+import kotlinx.coroutines.*
+import net.lingala.zip4j.ZipFile
+import net.lingala.zip4j.model.ZipParameters
+import net.lingala.zip4j.model.enums.AesKeyStrength
+import net.lingala.zip4j.model.enums.CompressionLevel
+import net.lingala.zip4j.model.enums.CompressionMethod
+import net.lingala.zip4j.model.enums.EncryptionMethod
+import java.io.File
+
+/**
+ * A single zip creation operation as a proper HybridObject instance.
+ *
+ * Uses zip4j for both standard and password-protected zip creation.
+ * AES-256 encryption when password is provided.
+ */
+@DoNotStrip
+@Keep
+class HybridZipTask(
+  private val sourcePath: String,
+  private val destinationZipPath: String,
+  private val password: String? = null
+) : HybridZipTaskSpec() {
+
+  override val memorySize: Long = 0L
+
+  override val taskId: String = "zip_${System.nanoTime()}_${(Math.random() * 1e9).toLong()}"
+
+  private var progressCallback: ((ZipProgress) -> Unit)? = null
+  private var compressionJob: Job? = null
+
+  @Volatile
+  private var shouldCancel = false
+
+  override fun onProgress(callback: (progress: ZipProgress) -> Unit) {
+    progressCallback = callback
+  }
+
+  override fun cancel() {
+    shouldCancel = true
+    compressionJob?.cancel()
+  }
+
+  override fun await(): Promise<ZipResult> {
+    return Promise.async { resolve, reject ->
+      try {
+        val result = compress()
+        resolve(result)
+      } catch (e: CancellationException) {
+        reject(Exception("Zip creation cancelled"))
+      } catch (e: Exception) {
+        reject(e)
+      }
+    }
+  }
+
+  private suspend fun compress(): ZipResult = withContext(Dispatchers.IO) {
+    compressionJob = coroutineContext[Job]
+
+    val startTime = System.currentTimeMillis()
+
+    val cleanSource = sourcePath.replace("file://", "")
+    val cleanDest = destinationZipPath.replace("file://", "")
+
+    val sourceDir = File(cleanSource)
+    if (!sourceDir.exists()) {
+      throw Exception("Source path not found: $cleanSource")
+    }
+
+    // Collect all files for progress tracking
+    val allFiles = mutableListOf<File>()
+    sourceDir.walkTopDown().forEach { file ->
+      if (file.isFile) {
+        allFiles.add(file)
+      }
+    }
+
+    val totalFiles = allFiles.size
+    var compressedCount = 0
+    var lastProgressUpdate = System.currentTimeMillis()
+
+    val zipFile = ZipFile(cleanDest)
+
+    val zipParams = ZipParameters().apply {
+      compressionMethod = CompressionMethod.DEFLATE
+      compressionLevel = CompressionLevel.NORMAL
+    }
+
+    if (password != null) {
+      zipFile.setPassword(password.toCharArray())
+      zipParams.isEncryptFiles = true
+      zipParams.encryptionMethod = EncryptionMethod.AES
+      zipParams.aesKeyStrength = AesKeyStrength.KEY_STRENGTH_256
+    }
+
+    // Add files one by one for progress tracking
+    for (file in allFiles) {
+      if (!isActive || shouldCancel) break
+
+      val relativePath = file.relativeTo(sourceDir).parent
+      val params = ZipParameters(zipParams)
+      if (relativePath != null) {
+        params.rootFolderNameInZip = relativePath
+      }
+
+      zipFile.addFile(file, params)
+      compressedCount++
+
+      val now = System.currentTimeMillis()
+      val shouldUpdate = (now - lastProgressUpdate >= PROGRESS_THROTTLE_MS)
+        || (compressedCount == totalFiles)
+        || (compressedCount == 1)
+
+      if (shouldUpdate) {
+        val progress = if (totalFiles > 0) compressedCount.toDouble() / totalFiles else 0.0
+        val elapsed = (now - startTime) / 1000.0
+        val speed = if (elapsed > 0) compressedCount / elapsed else 0.0
+
+        progressCallback?.invoke(
+          ZipProgress(
+            compressedFiles = compressedCount.toDouble(),
+            totalFiles = totalFiles.toDouble(),
+            progress = progress,
+            speed = speed
+          )
+        )
+        lastProgressUpdate = now
+      }
+    }
+
+    if (shouldCancel) {
+      // Clean up partial zip file
+      File(cleanDest).delete()
+      throw CancellationException("Zip creation cancelled")
+    }
+
+    val durationMs = (System.currentTimeMillis() - startTime).toDouble()
+    val avgSpeed = if (durationMs > 0) compressedCount / (durationMs / 1000.0) else 0.0
+    val totalBytes = File(cleanDest).length().toDouble()
+
+    ZipResult(
+      success = true,
+      compressedFiles = compressedCount.toDouble(),
+      duration = durationMs,
+      averageSpeed = avgSpeed,
+      totalBytes = totalBytes
+    )
+  }
+
+  companion object {
+    private const val PROGRESS_THROTTLE_MS = 1000L
+  }
+}

package/ios/HybridUnzip.swift

@@ -0,0 +1,33 @@
+import Foundation
+import NitroModules
+
+/**
+ * Factory HybridObject that creates extraction and compression tasks.
+ *
+ * Usage from JS:
+ * ```js
+ * const unzip = NitroModules.createHybridObject('Unzip')
+ * const task = unzip.extract(zipPath, destPath)
+ * const zipTask = unzip.zip(sourcePath, destZipPath)
+ * ```
+ */
+class HybridUnzip: HybridUnzipSpec {
+  var hybridContext = margelo.nitro.HybridContext()
+  var memorySize: Int { return getSizeOf(self) }
+
+  func extract(zipPath: String, destinationPath: String) throws -> any HybridUnzipTaskSpec {
+    return HybridUnzipTask(zipPath: zipPath, destinationPath: destinationPath)
+  }
+
+  func extractWithPassword(zipPath: String, destinationPath: String, password: String) throws -> any HybridUnzipTaskSpec {
+    return HybridUnzipTask(zipPath: zipPath, destinationPath: destinationPath, password: password)
+  }
+
+  func zip(sourcePath: String, destinationZipPath: String) throws -> any HybridZipTaskSpec {
+    return HybridZipTask(sourcePath: sourcePath, destinationZipPath: destinationZipPath)
+  }
+
+  func zipWithPassword(sourcePath: String, destinationZipPath: String, password: String) throws -> any HybridZipTaskSpec {
+    return HybridZipTask(sourcePath: sourcePath, destinationZipPath: destinationZipPath, password: password)
+  }
+}