react-native-nitro-unzip 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +107 -30
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,13 +1,19 @@
1
1
  # react-native-nitro-unzip
2
2
 
3
- High-performance ZIP extraction for React Native, powered by [Nitro Modules](https://nitro.margelo.com/).
3
+ [![npm](https://img.shields.io/npm/v/react-native-nitro-unzip)](https://www.npmjs.com/package/react-native-nitro-unzip)
4
+ [![license](https://img.shields.io/npm/l/react-native-nitro-unzip)](https://github.com/isaacrowntree/react-native-nitro-unzip/blob/main/LICENSE)
5
+ [![CI](https://github.com/isaacrowntree/react-native-nitro-unzip/actions/workflows/lint-typescript.yml/badge.svg)](https://github.com/isaacrowntree/react-native-nitro-unzip/actions/workflows/lint-typescript.yml)
6
+
7
+ High-performance ZIP operations for React Native, powered by [Nitro Modules](https://nitro.margelo.com/).
4
8
 
5
9
  - **iOS**: SSZipArchive (C-based libz) — ~500 files/sec
6
10
  - **Android**: Optimized ZipInputStream with 64KB buffers — ~474 files/sec
7
- - **Zero bridge overhead** for progress callbacks (JSI-based)
8
- - **Proper object instances** — each extraction is an `UnzipTask` you can observe and cancel
9
- - **Concurrent extractions** supported out of the box
10
- - **iOS background task** management for continued extraction when app is backgrounded
11
+ - **Zero bridge overhead** — progress callbacks via JSI, no serialization
12
+ - **Object instances** — each task is an observable, cancellable `UnzipTask` or `ZipTask`
13
+ - **Concurrent operations** supported out of the box
14
+ - **Password support** — AES-256 encrypted archives (zip4j on Android, SSZipArchive on iOS)
15
+ - **Zip creation** — compress files and directories with optional password protection
16
+ - **Background tasks** — iOS background task management for continued extraction
11
17
 
12
18
  ## Installation
13
19
 
@@ -16,26 +22,61 @@ npm install react-native-nitro-unzip react-native-nitro-modules
16
22
  cd ios && pod install
17
23
  ```
18
24
 
25
+ > Requires React Native 0.75+ and [Nitro Modules](https://nitro.margelo.com/) 0.34+
26
+
19
27
  ## Usage
20
28
 
29
+ ### Extract a ZIP archive
30
+
21
31
  ```typescript
22
- import { getUnzip } from 'react-native-nitro-unzip'
32
+ import { getUnzip } from 'react-native-nitro-unzip';
23
33
 
24
- const unzip = getUnzip()
25
- const task = unzip.extract('/path/to/archive.zip', '/path/to/output')
34
+ const unzip = getUnzip();
35
+ const task = unzip.extract('/path/to/archive.zip', '/path/to/output');
26
36
 
27
- // Track progress
28
37
  task.onProgress((p) => {
29
- console.log(`${(p.progress * 100).toFixed(0)}% — ${p.extractedFiles}/${p.totalFiles} files`)
30
- console.log(`Speed: ${p.speed.toFixed(0)} files/sec`)
31
- })
38
+ console.log(`${(p.progress * 100).toFixed(0)}% — ${p.extractedFiles}/${p.totalFiles} files`);
39
+ console.log(`Speed: ${p.speed.toFixed(0)} files/sec`);
40
+ });
32
41
 
33
- // Await result
34
- const result = await task.await()
35
- console.log(`Extracted ${result.extractedFiles} files in ${result.duration}ms`)
42
+ const result = await task.await();
43
+ console.log(`Extracted ${result.extractedFiles} files in ${result.duration}ms`);
44
+ ```
45
+
46
+ ### Extract with password
36
47
 
37
- // Or cancel
38
- task.cancel()
48
+ ```typescript
49
+ const task = unzip.extractWithPassword('/path/to/encrypted.zip', '/output', 'secret');
50
+ const result = await task.await();
51
+ ```
52
+
53
+ ### Create a ZIP archive
54
+
55
+ ```typescript
56
+ const task = unzip.zip('/path/to/folder', '/output/archive.zip');
57
+
58
+ task.onProgress((p) => {
59
+ console.log(`${(p.progress * 100).toFixed(0)}% — ${p.compressedFiles}/${p.totalFiles}`);
60
+ });
61
+
62
+ const result = await task.await();
63
+ console.log(`Compressed ${result.compressedFiles} files`);
64
+ ```
65
+
66
+ ### Create with password (AES-256)
67
+
68
+ ```typescript
69
+ const task = unzip.zipWithPassword('/path/to/folder', '/output/secure.zip', 'secret');
70
+ const result = await task.await();
71
+ ```
72
+
73
+ ### Cancel an operation
74
+
75
+ ```typescript
76
+ const task = unzip.extract('/path/to/large.zip', '/output');
77
+
78
+ // Cancel at any time — synchronous via JSI
79
+ task.cancel();
39
80
  ```
40
81
 
41
82
  ## API
@@ -44,21 +85,28 @@ task.cancel()
44
85
 
45
86
  Creates an `Unzip` factory instance.
46
87
 
47
- ### `Unzip.extract(zipPath, destinationPath): UnzipTask`
88
+ ### Extraction
48
89
 
49
- Starts extracting a ZIP archive. Returns an `UnzipTask` instance immediately.
90
+ | Method | Returns | Description |
91
+ |---|---|---|
92
+ | `extract(zipPath, destPath)` | `UnzipTask` | Extract a ZIP archive |
93
+ | `extractWithPassword(zipPath, destPath, password)` | `UnzipTask` | Extract a password-protected archive |
50
94
 
51
- - `zipPath` — absolute path to the ZIP file (`file://` URIs accepted)
52
- - `destinationPath` — absolute path to extract into (created if missing)
95
+ ### Compression
53
96
 
54
- ### `UnzipTask`
97
+ | Method | Returns | Description |
98
+ |---|---|---|
99
+ | `zip(sourcePath, destZipPath)` | `ZipTask` | Create a ZIP archive from a directory |
100
+ | `zipWithPassword(sourcePath, destZipPath, password)` | `ZipTask` | Create a password-protected ZIP (AES-256) |
101
+
102
+ ### `UnzipTask` / `ZipTask`
55
103
 
56
104
  | Property/Method | Type | Description |
57
105
  |---|---|---|
58
- | `taskId` | `string` | Unique identifier for this extraction |
59
- | `onProgress(callback)` | `(progress: UnzipProgress) => void` | Register a progress callback (throttled to ~1/sec) |
60
- | `cancel()` | `void` | Cancel this extraction |
61
- | `await()` | `Promise<UnzipResult>` | Await the extraction result |
106
+ | `taskId` | `string` | Unique identifier for this operation |
107
+ | `onProgress(callback)` | `void` | Register a progress callback (throttled ~1/sec) |
108
+ | `cancel()` | `void` | Cancel the operation (synchronous via JSI) |
109
+ | `await()` | `Promise<Result>` | Await the operation result |
62
110
 
63
111
  ### `UnzipProgress`
64
112
 
@@ -80,6 +128,25 @@ Starts extracting a ZIP archive. Returns an `UnzipTask` instance immediately.
80
128
  | `averageSpeed` | `number` | Average files per second |
81
129
  | `totalBytes` | `number` | Total bytes extracted |
82
130
 
131
+ ### `ZipProgress`
132
+
133
+ | Field | Type | Description |
134
+ |---|---|---|
135
+ | `compressedFiles` | `number` | Files compressed so far |
136
+ | `totalFiles` | `number` | Total files to compress |
137
+ | `progress` | `number` | 0.0 to 1.0 |
138
+ | `speed` | `number` | Files per second |
139
+
140
+ ### `ZipResult`
141
+
142
+ | Field | Type | Description |
143
+ |---|---|---|
144
+ | `success` | `boolean` | Whether compression completed |
145
+ | `compressedFiles` | `number` | Total files compressed |
146
+ | `duration` | `number` | Duration in milliseconds |
147
+ | `averageSpeed` | `number` | Average files per second |
148
+ | `totalBytes` | `number` | Total bytes written |
149
+
83
150
  ## Performance
84
151
 
85
152
  Benchmarked on a 350MB archive with 10,432 small files (map tiles):
@@ -97,10 +164,20 @@ Benchmarked on a 350MB archive with 10,432 small files (map tiles):
97
164
 
98
165
  ## Requirements
99
166
 
100
- - React Native 0.75+
101
- - Nitro Modules 0.34+
102
- - iOS 13+
103
- - Android SDK 21+
167
+ | Requirement | Version |
168
+ |---|---|
169
+ | React Native | 0.75+ |
170
+ | Nitro Modules | 0.34+ |
171
+ | iOS | 13+ |
172
+ | Android SDK | 21+ |
173
+
174
+ ## Example
175
+
176
+ See the [example app](./example) for a working demo of extraction, zip creation, password support, and cancellation.
177
+
178
+ ## Contributing
179
+
180
+ See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
104
181
 
105
182
  ## License
106
183
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "react-native-nitro-unzip",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "High-performance ZIP extraction for React Native, powered by Nitro Modules",
5
5
  "main": "lib/commonjs/index.js",
6
6
  "module": "lib/module/index.js",