feat: cancel() + stable error codes (#366)

.github/workflows/e2e.yml

@@ -46,8 +46,23 @@ jobs:
 
       - name: Install Maestro
         run: |
-          curl -fsSL "https://get.maestro.mobile.dev" | bash
-          echo "$HOME/.maestro/bin" >> $GITHUB_PATH
+          set -euo pipefail
+          for attempt in 1 2 3; do
+            echo "Installing Maestro (attempt $attempt)..."
+            if curl -fsSL "https://get.maestro.mobile.dev" | bash \
+              && test -x "$HOME/.maestro/bin/maestro"; then
+              break
+            fi
+            echo "Maestro install failed on attempt $attempt"
+            rm -rf "$HOME/.maestro"
+            if [ "$attempt" -eq 3 ]; then
+              echo "Maestro install failed after 3 attempts"
+              exit 1
+            fi
+            sleep $((attempt * 5))
+          done
+          echo "$HOME/.maestro/bin" >> "$GITHUB_PATH"
+          "$HOME/.maestro/bin/maestro" --version
 
       - name: Cache node_modules
         uses: actions/cache@v4
@@ -159,8 +174,23 @@ jobs:
 
       - name: Install Maestro
         run: |
-          curl -fsSL "https://get.maestro.mobile.dev" | bash
-          echo "$HOME/.maestro/bin" >> $GITHUB_PATH
+          set -euo pipefail
+          for attempt in 1 2 3; do
+            echo "Installing Maestro (attempt $attempt)..."
+            if curl -fsSL "https://get.maestro.mobile.dev" | bash \
+              && test -x "$HOME/.maestro/bin/maestro"; then
+              break
+            fi
+            echo "Maestro install failed on attempt $attempt"
+            rm -rf "$HOME/.maestro"
+            if [ "$attempt" -eq 3 ]; then
+              echo "Maestro install failed after 3 attempts"
+              exit 1
+            fi
+            sleep $((attempt * 5))
+          done
+          echo "$HOME/.maestro/bin" >> "$GITHUB_PATH"
+          "$HOME/.maestro/bin/maestro" --version
 
       - name: Cache node_modules
         uses: actions/cache@v4

.maestro/flows/_home-check.yaml

@@ -2,7 +2,16 @@ appId: ${APP_ID}
 ---
 - assertVisible: "Zip Operations"
 - assertVisible: "Unzip Operations"
+- assertVisible: "List & Selective Extract"
+- scrollUntilVisible:
+    element:
+      text: "Password Protection"
+    direction: DOWN
 - assertVisible: "Password Protection"
+- scrollUntilVisible:
+    element:
+      text: "Progress Events"
+    direction: DOWN
 - assertVisible: "Progress Events"
 - scrollUntilVisible:
     element:

.maestro/flows/_list-contents-test.yaml

@@ -0,0 +1,56 @@
+appId: ${APP_ID}
+---
+- runFlow:
+    when:
+      notVisible: "List & Selective Extract"
+    commands:
+      - tapOn: "Playground"
+- scrollUntilVisible:
+    element:
+      text: "List & Selective Extract"
+    direction: DOWN
+- tapOn: "List & Selective Extract"
+- extendedWaitUntil:
+    visible: "Create Zip and List Contents"
+    timeout: 15000
+- tapOn: "Create Zip and List Contents"
+- extendedWaitUntil:
+    visible: "Listed Entries"
+    timeout: 20000
+- assertVisible: "Listed Entries"
+- scrollUntilVisible:
+    element:
+      text: "Contains hello.txt"
+    direction: DOWN
+    timeout: 10000
+- assertVisible: "Contains hello.txt"
+- assertVisible: "Contains readme.md"
+- scrollUntilVisible:
+    element:
+      text: "Extract Selected Entries"
+    direction: DOWN
+- tapOn: "Extract Selected Entries"
+- extendedWaitUntil:
+    visible: "Selective Extract"
+    timeout: 20000
+- assertVisible: "Selective Extract"
+- scrollUntilVisible:
+    element:
+      text: "Extracted docs/guide.md"
+    direction: DOWN
+    timeout: 10000
+- assertVisible: "Extracted readme.md"
+- assertVisible: "Extracted docs/guide.md"
+- assertVisible: "Skipped hello.txt"
+- scrollUntilVisible:
+    element:
+      text: "Password Selective Extract"
+    direction: DOWN
+- tapOn: "Password Selective Extract"
+- extendedWaitUntil:
+    visible: "Password Selective Extract Done"
+    timeout: 30000
+- assertVisible: "Password Selective Extract Done"
+- assertVisible: "Extracted readme.md"
+- assertVisible: "Skipped hello.txt"
+- back

.maestro/flows/ci-master.yaml

@@ -4,6 +4,7 @@ appId: ${APP_ID}
 - runFlow: _home-check.yaml
 - runFlow: _zip-test.yaml
 - runFlow: _unzip-test.yaml
+- runFlow: _list-contents-test.yaml
 - runFlow: _password-test.yaml
 - runFlow: _progress-test.yaml
 - runFlow: _assets-test.yaml

.maestro/flows/list-contents.yaml

@@ -0,0 +1,4 @@
+appId: ${APP_ID}
+---
+- runFlow: _setup.yaml
+- runFlow: _list-contents-test.yaml

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [9.2.0] - 2026-07-25
+
+### Added
+- `cancel()` — best-effort abort of the in-flight zip/unzip operation; rejects with `ERR_CANCELLED` (#366)
+- Stable cross-platform error codes (`ERR_FILE_NOT_FOUND`, `ERR_WRONG_PASSWORD`, `ERR_UNSAFE_PATH`, …) and JS `ErrorCodes` map (#366)
+
+## [9.1.0] - 2026-07-25
+
+### Added
+- `listContents(source, charset?)` — inspect archive entries (path, sizes, directory/encrypted flags) without extracting (#365)
+- Optional `entries` on `unzip` / `unzipWithPassword` — extract only selected entry paths; directory names include nested children (#365)
+- Android unit tests for selective-extract entry matching
+
 ## [9.0.2] - 2026-07-22
 
 ### Fixed

README.md

@@ -38,10 +38,13 @@ import {
   zipWithPassword,
   unzip,
   unzipWithPassword,
+  listContents,
   unzipAssets,
+  cancel,
   subscribe,
   isPasswordProtected,
   getUncompressedSize,
+  ErrorCodes,
   DEFAULT_COMPRESSION,
   NO_COMPRESSION,
   BEST_SPEED,
@@ -104,9 +107,21 @@ zipWithPassword(sourcePath, targetPath, 'password', 'STANDARD')
   .catch((error) => console.error(error))
 ```
 
-### `unzip(source: string, target: string, charset?: string): Promise<string>`
+### `unzip(source: string, target: string, charset?: string | string[], entries?: string[]): Promise<string>`
 
-Unzip from source to target.
+Unzip from source to target. Pass `entries` to extract only those paths; directory names match that entry and all nested children (e.g. `'docs'` extracts `docs/` and `docs/readme.md`).
+
+You can pass entries as the third argument when using the default charset:
+
+```js
+unzip(sourcePath, targetPath, ['readme.md', 'docs'])
+```
+
+Or with an explicit charset:
+
+```js
+unzip(sourcePath, targetPath, 'UTF-8', ['readme.md', 'docs'])
+```
 
 > The `charset` parameter is only supported on Android (default: `UTF-8`). On iOS it is ignored.
 
@@ -119,14 +134,44 @@ unzip(sourcePath, targetPath, 'UTF-8')
   .catch((error) => console.error(error))
 ```
 
-### `unzipWithPassword(source: string, target: string, password: string): Promise<string>`
+### `unzipWithPassword(source: string, target: string, password: string, entries?: string[]): Promise<string>`
 
-Unzip a password-protected archive.
+Unzip a password-protected archive. Pass `entries` to extract only those paths.
 
 ```js
 unzipWithPassword(sourcePath, targetPath, 'password')
   .then((path) => console.log(`unzip completed at ${path}`))
   .catch((error) => console.error(error))
+
+unzipWithPassword(sourcePath, targetPath, 'password', ['secret.txt'])
+  .then((path) => console.log(`selective unzip completed at ${path}`))
+  .catch((error) => console.error(error))
+```
+
+### `listContents(source: string, charset?: string): Promise<ZipEntry[]>`
+
+List archive entries without extracting.
+
+```ts
+type ZipEntry = {
+  path: string
+  size: number           // uncompressed size in bytes
+  compressedSize: number
+  isDirectory: boolean
+  isEncrypted: boolean
+}
+```
+
+> The `charset` parameter is only supported on Android (default: `UTF-8`). On iOS it is ignored.
+
+```js
+listContents(sourcePath)
+  .then((entries) => {
+    entries.forEach((entry) => {
+      console.log(entry.path, entry.size, entry.isDirectory)
+    })
+  })
+  .catch((error) => console.error(error))
 ```
 
 ### `unzipAssets(assetPath: string, target: string): Promise<string>`
@@ -153,6 +198,39 @@ getUncompressedSize(sourcePath)
   .catch((error) => console.error(error))
 ```
 
+### `cancel(): Promise<void>`
+
+Cancel the in-flight zip/unzip operation (best-effort). The active operation's promise rejects with `ErrorCodes.CANCELLED` (`ERR_CANCELLED`).
+
+```js
+const unzipPromise = unzip(sourcePath, targetPath)
+cancel()
+unzipPromise.catch((error) => {
+  if (error.code === ErrorCodes.CANCELLED) {
+    console.log('unzip cancelled')
+  }
+})
+```
+
+### Error codes
+
+Native rejections use stable `error.code` values on both platforms:
+
+| Code | When |
+|------|------|
+| `ERR_FILE_NOT_FOUND` | Source missing |
+| `ERR_INVALID_PATH` | Bad / null path |
+| `ERR_INVALID_ARGS` | Empty password, empty entries, etc. |
+| `ERR_WRONG_PASSWORD` | Password decrypt failed |
+| `ERR_NOT_PASSWORD_PROTECTED` | Password API used on a plain archive |
+| `ERR_CORRUPT_ARCHIVE` | Not a zip / truncated / unreadable |
+| `ERR_UNSAFE_PATH` | Zip Slip / path traversal |
+| `ERR_CANCELLED` | `cancel()` interrupted the operation |
+| `ERR_ZIP` / `ERR_UNZIP` | Generic zip/unzip failure |
+| `ERR_UNSUPPORTED` | API not available on this platform |
+
+Also exported as the `ErrorCodes` constant map.
+
 ### `subscribe(callback: ({ progress: number, filePath: string }) => void): EmitterSubscription`
 
 Subscribe to progress events. Useful for showing a progress bar.
@@ -187,9 +265,11 @@ useEffect(() => {
 | `zip` (files array) | ✅ | ✅ | Compression level ignored on iOS |
 | `zipWithPassword` (folder) | ✅ | ✅ | AES encryption supported |
 | `zipWithPassword` (files array) | ⚠️ | ✅ | iOS: only `STANDARD` encryption |
-| `unzip` | ✅ | ✅ | Charset ignored on iOS |
-| `unzipWithPassword` | ✅ | ✅ | — |
+| `unzip` | ✅ | ✅ | Optional `entries` for selective extract; charset ignored on iOS |
+| `unzipWithPassword` | ✅ | ✅ | Optional `entries` for selective extract |
+| `listContents` | ✅ | ✅ | Charset ignored on iOS |
 | `unzipAssets` | ❌ | ✅ | Android only |
+| `cancel` | ✅ | ✅ | Best-effort mid-operation abort |
 | `isPasswordProtected` | ✅ | ✅ | — |
 | `getUncompressedSize` | ✅ | ✅ | Charset ignored on iOS |
 | Progress Events | ✅ | ✅ | File path empty on iOS for zip |

RNZipArchive.podspec

@@ -12,6 +12,9 @@ Pod::Spec.new do |s|
   s.source         = { :git => 'https://github.com/mockingbot/react-native-zip-archive.git', :tag => "#{s.version}"}
   s.platform       = :ios, '15.5'
   s.preserve_paths = '*.js'
+  s.pod_target_xcconfig = {
+    'HEADER_SEARCH_PATHS' => '$(inherited) "$(PODS_ROOT)/SSZipArchive/SSZipArchive/minizip"'
+  }
 
   if defined?(install_modules_dependencies) != nil
     install_modules_dependencies(s)

__mocks__/react-native.js

@@ -6,9 +6,21 @@ const mockRNZipArchive = {
   zipFilesWithPassword: jest.fn(() => Promise.resolve('/mock/path.zip')),
   unzip: jest.fn(() => Promise.resolve('/mock/dest')),
   unzipWithPassword: jest.fn(() => Promise.resolve('/mock/dest')),
+  listContents: jest.fn(() =>
+    Promise.resolve([
+      {
+        path: 'hello.txt',
+        size: 12,
+        compressedSize: 10,
+        isDirectory: false,
+        isEncrypted: false,
+      },
+    ])
+  ),
   unzipAssets: jest.fn(() => Promise.resolve('/mock/dest')),
   isPasswordProtected: jest.fn(() => Promise.resolve(true)),
   getUncompressedSize: jest.fn(() => Promise.resolve(1024)),
+  cancel: jest.fn(() => Promise.resolve()),
   addListener: jest.fn(),
   removeListeners: jest.fn(),
 };