Skip to content

Commit 6c79596

Browse files
isaacrowntreeclaude
isaacrowntree
and
claude
committed
docs: add Docusaurus docs site with TypeDoc API reference
Set up a Docusaurus site in docs/ with auto-generated API docs from TypeScript via docusaurus-plugin-typedoc. Includes hand-written guides for getting started, extraction, compression, password protection, cancellation, and performance. Adds GitHub Actions workflow for deploying to GitHub Pages. Slims down README to point to the docs site. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent c41f808 commit 6c79596

19 files changed

Lines changed: 19572 additions & 152 deletions

‎.github/workflows/deploy-docs.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
23+
- uses: actions/setup-node@v4
24+
with:
25+
node-version: 20
26+
27+
- name: Install root dependencies
28+
run: npm install
29+
30+
- name: Install docs dependencies
31+
working-directory: docs
32+
run: npm install
33+
34+
- name: Build docs
35+
working-directory: docs
36+
run: npm run build
37+
38+
- name: Upload artifact
39+
uses: actions/upload-pages-artifact@v3
40+
with:
41+
path: docs/build
42+
43+
deploy:
44+
environment:
45+
name: github-pages
46+
url: ${{ steps.deployment.outputs.page_url }}
47+
runs-on: ubuntu-latest
48+
needs: build
49+
steps:
50+
- name: Deploy to GitHub Pages
51+
id: deployment
52+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,12 @@ example/android/build/
2929
example/android/.gradle/
3030
example/.expo/
3131

32+
# Docs
33+
docs/build/
34+
docs/node_modules/
35+
docs/.docusaurus/
36+
docs/docs/api/
37+
3238
# OS
3339
.DS_Store
3440
Thumbs.db

‎README.md‎

Lines changed: 21 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -9,26 +9,17 @@
99

1010
High-performance ZIP operations for React Native, powered by [Nitro Modules](https://nitro.margelo.com/).
1111

12-
- **iOS**: [SSZipArchive](https://github.com/ZipArchive/ZipArchive) (C-based libz) — ~500 files/sec
13-
- **Android**: Optimized ZipInputStream + [zip4j](https://github.com/srikanth-lingala/zip4j) for encryption — ~474 files/sec
12+
**[Read the full documentation](https://isaacrowntree.github.io/react-native-nitro-unzip/)**
13+
14+
## Features
15+
16+
- **Fast** — ~500 files/sec (iOS), ~474 files/sec (Android) on a 350MB / 10k file archive
1417
- **Zero bridge overhead** — progress callbacks via JSI, no serialization
15-
- **Object instances** — each task is an observable, cancellable `UnzipTask` or `ZipTask`
16-
- **Concurrent operations** supported out of the box
17-
- **Password support** — AES-256 encrypted archives (zip4j on Android, SSZipArchive on iOS)
18-
- **Zip creation** — compress files and directories with optional password protection
19-
- **Background tasks** — iOS background task management for continued extraction
20-
21-
### vs react-native-zip-archive
22-
23-
| | react-native-nitro-unzip | react-native-zip-archive |
24-
|---|---|---|
25-
| Architecture | JSI (Nitro Modules) | Bridge |
26-
| Progress callbacks | Via JSI, no serialization | Via bridge events |
27-
| Cancellation | Synchronous | Not supported |
28-
| Concurrent ops | Yes | Limited |
29-
| Password support | AES-256 (zip & unzip) | Unzip only |
30-
| Zip creation | Yes | Yes |
31-
| New Architecture | Required | Optional |
18+
- **Cancellable** — synchronous cancellation via JSI
19+
- **Password support** — AES-256 encrypted archives (zip & unzip)
20+
- **Zip creation** — compress directories with optional password protection
21+
- **Concurrent operations** — multiple tasks run independently
22+
- **Background execution** — iOS background task management
3223

3324
## Installation
3425

@@ -39,9 +30,7 @@ cd ios && pod install
3930

4031
> Requires React Native 0.75+ and [Nitro Modules](https://nitro.margelo.com/) 0.34+
4132
42-
## Usage
43-
44-
### Extract a ZIP archive
33+
## Quick Example
4534

4635
```typescript
4736
import { getUnzip } from 'react-native-nitro-unzip';
@@ -51,146 +40,27 @@ const task = unzip.extract('/path/to/archive.zip', '/path/to/output');
5140

5241
task.onProgress((p) => {
5342
console.log(`${(p.progress * 100).toFixed(0)}% — ${p.extractedFiles}/${p.totalFiles} files`);
54-
console.log(`Speed: ${p.speed.toFixed(0)} files/sec`);
5543
});
5644

5745
const result = await task.await();
5846
console.log(`Extracted ${result.extractedFiles} files in ${result.duration}ms`);
5947
```
6048

61-
### Extract with password
62-
63-
```typescript
64-
const task = unzip.extractWithPassword('/path/to/encrypted.zip', '/output', 'secret');
65-
const result = await task.await();
66-
```
67-
68-
### Create a ZIP archive
69-
70-
```typescript
71-
const task = unzip.zip('/path/to/folder', '/output/archive.zip');
72-
73-
task.onProgress((p) => {
74-
console.log(`${(p.progress * 100).toFixed(0)}% — ${p.compressedFiles}/${p.totalFiles}`);
75-
});
76-
77-
const result = await task.await();
78-
console.log(`Compressed ${result.compressedFiles} files`);
79-
```
80-
81-
### Create with password (AES-256)
82-
83-
```typescript
84-
const task = unzip.zipWithPassword('/path/to/folder', '/output/secure.zip', 'secret');
85-
const result = await task.await();
86-
```
87-
88-
### Cancel an operation
89-
90-
```typescript
91-
const task = unzip.extract('/path/to/large.zip', '/output');
92-
93-
// Cancel at any time — synchronous via JSI
94-
task.cancel();
95-
```
96-
97-
## API
98-
99-
### `getUnzip(): Unzip`
100-
101-
Creates an `Unzip` factory instance.
102-
103-
### Extraction
104-
105-
| Method | Returns | Description |
106-
|---|---|---|
107-
| `extract(zipPath, destPath)` | `UnzipTask` | Extract a ZIP archive |
108-
| `extractWithPassword(zipPath, destPath, password)` | `UnzipTask` | Extract a password-protected archive |
109-
110-
### Compression
111-
112-
| Method | Returns | Description |
113-
|---|---|---|
114-
| `zip(sourcePath, destZipPath)` | `ZipTask` | Create a ZIP archive from a directory |
115-
| `zipWithPassword(sourcePath, destZipPath, password)` | `ZipTask` | Create a password-protected ZIP (AES-256) |
116-
117-
### `UnzipTask` / `ZipTask`
118-
119-
| Property/Method | Type | Description |
120-
|---|---|---|
121-
| `taskId` | `string` | Unique identifier for this operation |
122-
| `onProgress(callback)` | `void` | Register a progress callback (throttled ~1/sec) |
123-
| `cancel()` | `void` | Cancel the operation (synchronous via JSI) |
124-
| `await()` | `Promise<Result>` | Await the operation result |
125-
126-
### `UnzipProgress`
127-
128-
| Field | Type | Description |
129-
|---|---|---|
130-
| `extractedFiles` | `number` | Files extracted so far |
131-
| `totalFiles` | `number` | Total files in archive |
132-
| `progress` | `number` | 0.0 to 1.0 |
133-
| `speed` | `number` | Files per second |
134-
| `processedBytes` | `number` | Bytes processed |
135-
136-
### `UnzipResult`
137-
138-
| Field | Type | Description |
139-
|---|---|---|
140-
| `success` | `boolean` | Whether extraction completed |
141-
| `extractedFiles` | `number` | Total files extracted |
142-
| `totalFiles` | `number` | Total files in the archive |
143-
| `duration` | `number` | Duration in milliseconds |
144-
| `averageSpeed` | `number` | Average files per second |
145-
| `totalBytes` | `number` | Size of the ZIP file in bytes |
146-
147-
### `ZipProgress`
148-
149-
| Field | Type | Description |
150-
|---|---|---|
151-
| `compressedFiles` | `number` | Files compressed so far |
152-
| `totalFiles` | `number` | Total files to compress |
153-
| `progress` | `number` | 0.0 to 1.0 |
154-
| `speed` | `number` | Files per second |
155-
156-
### `ZipResult`
157-
158-
| Field | Type | Description |
159-
|---|---|---|
160-
| `success` | `boolean` | Whether compression completed |
161-
| `compressedFiles` | `number` | Total files compressed |
162-
| `totalFiles` | `number` | Total files to compress |
163-
| `duration` | `number` | Duration in milliseconds |
164-
| `averageSpeed` | `number` | Average files per second |
165-
| `totalBytes` | `number` | Total bytes written |
166-
167-
## Performance
168-
169-
Benchmarked on a 350MB archive with 10,432 small files (map tiles):
170-
171-
| Platform | Speed | Time |
172-
|---|---|---|
173-
| iOS (iPhone) | ~500 files/sec | ~20s |
174-
| Android | ~474 files/sec | ~22s |
175-
176-
### Why it's fast
177-
178-
- **iOS**: SSZipArchive uses C-based libz decompression with streaming extraction
179-
- **Android**: 64KB I/O buffers (8x default), batch directory creation, buffered streams
180-
- **Both**: Progress callbacks go through JSI (no bridge serialization), throttled to 1/sec
49+
## Documentation
18150

182-
## Requirements
51+
Visit the **[docs site](https://isaacrowntree.github.io/react-native-nitro-unzip/)** for:
18352

184-
| Requirement | Version |
185-
|---|---|
186-
| React Native | 0.75+ |
187-
| Nitro Modules | 0.34+ |
188-
| iOS | 13+ |
189-
| Android SDK | 21+ |
53+
- [Getting Started](https://isaacrowntree.github.io/react-native-nitro-unzip/docs/getting-started) — installation and setup
54+
- [Extraction](https://isaacrowntree.github.io/react-native-nitro-unzip/docs/usage/extraction) — extract archives with progress
55+
- [Compression](https://isaacrowntree.github.io/react-native-nitro-unzip/docs/usage/compression) — create ZIP archives
56+
- [Password Protection](https://isaacrowntree.github.io/react-native-nitro-unzip/docs/usage/password) — encrypted archives
57+
- [Cancellation](https://isaacrowntree.github.io/react-native-nitro-unzip/docs/usage/cancellation) — cancel operations
58+
- [Performance](https://isaacrowntree.github.io/react-native-nitro-unzip/docs/performance) — benchmarks and internals
59+
- [API Reference](https://isaacrowntree.github.io/react-native-nitro-unzip/docs/api) — auto-generated from TypeScript
19060

19161
## Example
19262

193-
See the [example app](./example) for a working demo of extraction, zip creation, password support, and cancellation.
63+
See the [example app](./example) for a working demo.
19464

19565
## Contributing
19666

‎docs/docs/getting-started.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Getting Started
6+
7+
react-native-nitro-unzip provides high-performance ZIP extraction and compression for React Native, powered by [Nitro Modules](https://nitro.margelo.com/).
8+
9+
## Requirements
10+
11+
| Requirement | Version |
12+
|---|---|
13+
| React Native | 0.75+ |
14+
| Nitro Modules | 0.34+ |
15+
| iOS | 13+ |
16+
| Android SDK | 21+ |
17+
18+
:::info New Architecture Required
19+
This library requires React Native's New Architecture (Fabric + TurboModules) as it is built on Nitro Modules.
20+
:::
21+
22+
## Installation
23+
24+
```bash
25+
npm install react-native-nitro-unzip react-native-nitro-modules
26+
```
27+
28+
### iOS
29+
30+
```bash
31+
cd ios && pod install
32+
```
33+
34+
### Android
35+
36+
No additional setup needed — the library auto-links with React Native.
37+
38+
## Quick Start
39+
40+
```typescript
41+
import { getUnzip } from 'react-native-nitro-unzip';
42+
43+
// Create an Unzip instance
44+
const unzip = getUnzip();
45+
46+
// Extract a ZIP archive
47+
const task = unzip.extract('/path/to/archive.zip', '/path/to/output');
48+
49+
task.onProgress((p) => {
50+
console.log(`${(p.progress * 100).toFixed(0)}% — ${p.extractedFiles}/${p.totalFiles} files`);
51+
});
52+
53+
const result = await task.await();
54+
console.log(`Extracted ${result.extractedFiles} files in ${result.duration}ms`);
55+
```
56+
57+
The `getUnzip()` function creates an `Unzip` factory instance. From there you can create extraction tasks, compression tasks, and more. Each task is an independent, observable, and cancellable operation.
58+
59+
## Next Steps
60+
61+
- [Extraction](./usage/extraction) — extracting ZIP archives with progress tracking
62+
- [Compression](./usage/compression) — creating ZIP archives from directories
63+
- [Password Protection](./usage/password) — working with encrypted archives
64+
- [Cancellation](./usage/cancellation) — cancelling in-progress operations

‎docs/docs/performance.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# Performance
6+
7+
react-native-nitro-unzip is designed for speed. Here's how it performs and why.
8+
9+
## Benchmarks
10+
11+
Tested on a 350MB archive with 10,432 small files (map tiles):
12+
13+
| Platform | Speed | Time |
14+
|---|---|---|
15+
| iOS (iPhone) | ~500 files/sec | ~20s |
16+
| Android | ~474 files/sec | ~22s |
17+
18+
## Why It's Fast
19+
20+
### iOS
21+
22+
[SSZipArchive](https://github.com/ZipArchive/ZipArchive) uses C-based **libz** decompression with streaming extraction, avoiding memory overhead from loading the entire archive into memory.
23+
24+
### Android
25+
26+
The Android implementation uses several optimizations:
27+
28+
- **64KB I/O buffers** — 8x the default buffer size, reducing system call overhead
29+
- **Batch directory creation** — creates directory trees in bulk rather than one at a time
30+
- **Buffered streams** — wraps all I/O in buffered streams for efficient reads and writes
31+
32+
### Both Platforms
33+
34+
- **JSI callbacks** — progress updates go through JSI (JavaScript Interface), bypassing the React Native bridge entirely. No serialization or deserialization overhead.
35+
- **Throttled updates** — progress callbacks fire at most once per second, so even archives with thousands of files don't flood the JS thread.
36+
- **Background execution** — extraction runs on native background threads, keeping the UI responsive.
37+
38+
## vs react-native-zip-archive
39+
40+
| | react-native-nitro-unzip | react-native-zip-archive |
41+
|---|---|---|
42+
| Architecture | JSI (Nitro Modules) | Bridge |
43+
| Progress callbacks | Via JSI, no serialization | Via bridge events |
44+
| Cancellation | Synchronous | Not supported |
45+
| Concurrent ops | Yes | Limited |
46+
| Password support | AES-256 (zip & unzip) | Unzip only |
47+
| Zip creation | Yes | Yes |
48+
| New Architecture | Required | Optional |

0 commit comments

Comments
 (0)