rn-file-toolkit 1.0.4 → 1.0.6

package/README.md

@@ -16,8 +16,10 @@
 ⭐ **Star this repo if you find it useful to help others discover it!**
 
 ## 📖 Table of Contents
+
 - [Why rn-file-toolkit?](#-why-rn-file-toolkit)
 - [Why not Expo FileSystem?](#-why-not-expo-filesystem)
+- [Documentation Website](#-documentation-website)
 - [Installation](#-installation)
 - [Quick Start: `useDownload`](#-quick-start-usedownload)
 - [Core APIs](#-core-apis)
@@ -37,6 +39,7 @@
 Most React Native file solutions (`rn-fetch-blob`, `react-native-fs`) are fragmented, lightly maintained, or lack modern features. **rn-file-toolkit** gives you a unified, **TurboModule-compatible** API utilizing OS-native managers (`URLSession` on iOS, `DownloadManager` on Android) for reliable, battery-efficient operations.
 
 ### ✨ Highlights
+
 - 🪝 **Drop-in React Hooks:** Built-in state management (`useDownload`) for progress and controls.
 - 📥 **Background Ready:** Downloads and uploads survive app suspension with automatic re-attachment.
 - 🚦 **Smart Queueing:** Cap concurrency and set priorities without touching native code.
@@ -47,16 +50,34 @@ Most React Native file solutions (`rn-fetch-blob`, `react-native-fs`) are fragme
 
 ---
 
-## 🤔 Why not Expo FileSystem?
+## 🥊 How does it compare?
+
+If you've been working with React Native for a while, you've probably used `rn-fetch-blob` or `react-native-fs`. While they were fantastic tools back in the day, they haven't aged well and often struggle with modern requirements like seamless Expo integration or background persistence. You might have also tried `expo-file-system`, which is great for the basics but starts to fall short when you need smart queueing or multipart uploads.
+
+We built **rn-file-toolkit** because we were tired of stitching together multiple unmaintained libraries just to download a file reliably in the background while keeping the UI updated.
+
+Here's how it stacks up against the crowd:
+
+| Feature | `rn-file-toolkit` | `react-native-fs` & `rn-fetch-blob` | `expo-file-system` |
+| :--- | :---: | :---: | :---: |
+| **Background Persistence** | ✅ Yes | ⚠️ Spotty / Legacy | ✅ Yes |
+| **Smart Queueing & Concurrency** | ✅ Built-in | ❌ Write your own | ❌ Write your own |
+| **React Hooks (`useDownload`)** | ✅ Out-of-the-box | ❌ Manual | ❌ Manual |
+| **Auto-Retries & Resumption** | ✅ Yes | ❌ Manual | ⚠️ Basic resume only |
+| **Multipart Uploads** | ✅ Yes (Memory efficient) | ⚠️ Basic support | ✅ Yes |
+| **Expo Support (Custom Dev Client)**| ✅ Seamless | ❌ Requires heavy config | ✅ Seamless |
+| **Zero 3rd-party Dependencies** | ✅ Yes | ❌ Varies | ✅ Yes |
+| **Active Maintenance** | ✅ Yes | ❌ Largely unmaintained | ✅ Yes |
+
+We hook directly into OS-level managers (`URLSession` on iOS, `DownloadManager` on Android) to provide maximum reliability, battery efficiency, and zero headaches.
+
+---
+
+## 🌐 Documentation Website
 
-Many developers looking for an **"expo-file-system alternative"** or a **"better react native download manager"** come here. While Expo FileSystem is a great tool for basic file operations, `rn-file-toolkit` is built specifically to handle complex, real-world file management scenarios:
+Full docs are hosted on GitHub Pages:
 
-- **Queueing & Concurrency:** Built-in smart queueing allows you to cap concurrent downloads and set priorities without writing complex JavaScript wrappers.
-- **Native Download/Upload Managers:** We hook directly into OS-level managers (`URLSession` on iOS, `DownloadManager` on Android) for maximum reliability and battery efficiency.
-- **Auto-Retries & Resiliency:** Native implementations handle network drops with exponential backoff and HTTP resume automatically.
-- **Multipart Uploads:** Robust, memory-efficient multipart uploads for large media are built right in.
-- **Drop-in React Hooks:** Provides a `useDownload` hook out-of-the-box for instant progress tracking, speed, ETA, and state controls.
-- **Background Persistence:** Downloads and uploads survive app suspension and backgrounding, automatically re-attaching when the app resumes.
+https://chavan-labs.github.io/rn-file-toolkit/
 
 ---
 
@@ -73,7 +94,7 @@ yarn add rn-file-toolkit
 pnpm add rn-file-toolkit
 ```
 
-*(Optional) If you are not using Expo or an auto-linking setup, run `pod install` in your `ios` directory.*
+_(Optional) If you are not using Expo or an auto-linking setup, run `pod install` in your `ios` directory._
 
 ---
 
@@ -87,22 +108,27 @@ import { View, Text, Button } from 'react-native';
 import { useDownload } from 'rn-file-toolkit';
 
 export default function DownloadScreen() {
-  const { start, pause, resume, cancel, status, progress, result } = useDownload();
+  const { start, pause, resume, cancel, status, progress, result } =
+    useDownload();
 
   return (
     <View style={{ padding: 20 }}>
-      <Button 
-        title="Start Download" 
-        onPress={() => start({ 
-          url: 'https://example.com/large-video.mp4', 
-          destination: 'documents' 
-        })} 
+      <Button
+        title="Start Download"
+        onPress={() =>
+          start({
+            url: 'https://example.com/large-video.mp4',
+            destination: 'documents',
+          })
+        }
       />
 
       {status === 'downloading' && progress && (
         <View style={{ marginTop: 20 }}>
           <Text>Progress: {progress.percent.toFixed(1)}%</Text>
-          <Text>Speed: {(progress.speedBps / 1024 / 1024).toFixed(2)} MB/s</Text>
+          <Text>
+            Speed: {(progress.speedBps / 1024 / 1024).toFixed(2)} MB/s
+          </Text>
           <Text>ETA: {progress.etaSeconds.toFixed(0)} seconds</Text>
           <View style={{ flexDirection: 'row', gap: 10, marginTop: 10 }}>
             <Button title="Pause" onPress={pause} />
@@ -112,8 +138,12 @@ export default function DownloadScreen() {
       )}
 
       {status === 'paused' && <Button title="Resume" onPress={resume} />}
-      {status === 'done' && <Text style={{ color: 'green' }}>✅ Saved: {result?.filePath}</Text>}
-      {status === 'error' && <Text style={{ color: 'red' }}>❌ Error: {result?.error}</Text>}
+      {status === 'done' && (
+        <Text style={{ color: 'green' }}>✅ Saved: {result?.filePath}</Text>
+      )}
+      {status === 'error' && (
+        <Text style={{ color: 'red' }}>❌ Error: {result?.error}</Text>
+      )}
     </View>
   );
 }
@@ -124,6 +154,7 @@ export default function DownloadScreen() {
 ## 🛠️ Core APIs
 
 ### Background Downloads
+
 For programmatic, queue-aware background downloads outside of React components.
 
 ```typescript
@@ -135,14 +166,15 @@ setQueueOptions({ maxConcurrent: 3 });
 const result = await download({
   url: 'https://example.com/file.pdf',
   destination: 'documents', // 'downloads' | 'cache' | 'documents'
-  queue: true,              // Join the managed queue
-  priority: 'high',         // 'high' | 'normal'
+  queue: true, // Join the managed queue
+  priority: 'high', // 'high' | 'normal'
   retry: { attempts: 3, delay: 1000 },
   onProgress: (p) => console.log(`${p.percent.toFixed(1)}% downloaded`),
 });
 ```
 
 ### Multipart Uploads
+
 Robust, memory-efficient multipart file uploading for large media or documents.
 
 ```typescript
@@ -158,6 +190,7 @@ const result = await upload({
 ```
 
 ### File System (FS)
+
 Perform native filesystem operations securely.
 
 ```typescript
@@ -180,6 +213,7 @@ await fs.deleteFile('/path/unwanted.txt');
 ```
 
 ### Zip & Unzip Archives
+
 Compress and extract archives directly on the device.
 
 ```typescript
@@ -193,16 +227,22 @@ await zip('/path/to/user-data-folder', '/path/to/backup.zip');
 ```
 
 ### Media & Utilities
+
 Helpful tools for sharing, opening, and encoding files.
 
 ```typescript
-import { saveBase64AsFile, urlToBase64, shareFile, openFile } from 'rn-file-toolkit';
+import {
+  saveBase64AsFile,
+  urlToBase64,
+  shareFile,
+  openFile,
+} from 'rn-file-toolkit';
 
 // Base64 to File
-await saveBase64AsFile({ 
-  base64Data: 'data:image/png;base64,...', 
+await saveBase64AsFile({
+  base64Data: 'data:image/png;base64,...',
   destination: 'documents',
-  fileName: 'image.png'
+  fileName: 'image.png',
 });
 
 // URL to Base64 (Great for caching small images)
@@ -212,28 +252,31 @@ const b64 = await urlToBase64({ url: 'https://example.com/icon.png' });
 await shareFile({ filePath: '/path/to/report.pdf' });
 
 // Open with default system app
-await openFile({ filePath: '/path/to/report.pdf', mimeType: 'application/pdf' });
+await openFile({
+  filePath: '/path/to/report.pdf',
+  mimeType: 'application/pdf',
+});
 ```
 
 ---
 
 ## 📚 API Reference
 
-| Interface | Key Properties | Description |
-| :--- | :--- | :--- |
-| `DownloadOptions` | `url`, `destination`, `queue`, `retry`, `onProgress` | Configuration for downloading a file. |
-| `UploadOptions` | `url`, `filePath`, `fieldName`, `parameters`, `onProgress` | Configuration for multipart uploads. |
-| `ProgressInfo` | `percent`, `bytesDownloaded`, `speedBps`, `etaSeconds` | Rich real-time progress payload. |
-| `UseDownloadReturn` | `start`, `pause`, `resume`, `cancel`, `status`, `progress` | Hook state and control methods. |
-| `FsStat` | `size`, `modified`, `isDir` | Output of the filesystem `stat` method. |
+| Interface           | Key Properties                                             | Description                             |
+| :------------------ | :--------------------------------------------------------- | :-------------------------------------- |
+| `DownloadOptions`   | `url`, `destination`, `queue`, `retry`, `onProgress`       | Configuration for downloading a file.   |
+| `UploadOptions`     | `url`, `filePath`, `fieldName`, `parameters`, `onProgress` | Configuration for multipart uploads.    |
+| `ProgressInfo`      | `percent`, `bytesDownloaded`, `speedBps`, `etaSeconds`     | Rich real-time progress payload.        |
+| `UseDownloadReturn` | `start`, `pause`, `resume`, `cancel`, `status`, `progress` | Hook state and control methods.         |
+| `FsStat`            | `size`, `modified`, `isDir`                                | Output of the filesystem `stat` method. |
 
-*For advanced types and detailed parameter documentation, please refer to the source TypeScript definitions.*
+_For advanced types and detailed parameter documentation, please refer to the source TypeScript definitions._
 
 ---
 
 ## 🎪 Expo Support
 
-**rn-file-toolkit** works seamlessly with Expo custom development clients (EAS Build / `npx expo run:android` / `npx expo run:ios`). Since it contains native code, it is not compatible with Expo Go. 
+**rn-file-toolkit** works seamlessly with Expo custom development clients (EAS Build / `npx expo run:android` / `npx expo run:ios`). Since it contains native code, it is not compatible with Expo Go.
 
 An Expo config plugin is included automatically. No extra configuration is needed in your `app.json` unless you want to customize permissions.
 
@@ -241,7 +284,7 @@ An Expo config plugin is included automatically. No extra configuration is neede
 
 ## 🤝 Contributing
 
-Contributions are welcome! If you find a bug or want to request a feature, please [open an issue](https://github.com/chavan-labs/rn-file-toolkit/issues). 
+Contributions are welcome! If you find a bug or want to request a feature, please [open an issue](https://github.com/chavan-labs/rn-file-toolkit/issues).
 
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/AmazingFeature`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rn-file-toolkit",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "The ultimate native file management toolkit for React Native. Features background downloads, resumable uploads, filesystem operations, queues, zip/unzip, and media utilities with zero third-party dependencies.",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",
@@ -55,6 +55,7 @@
     "android",
     "download",
     "downloader",
+    "file-toolkit",
     "file-download",
     "background-download",
     "download-manager",
@@ -123,7 +124,7 @@
   "bugs": {
     "url": "https://github.com/chavan-labs/rn-file-toolkit/issues"
   },
-  "homepage": "https://github.com/chavan-labs/rn-file-toolkit#readme",
+  "homepage": "https://chavan-labs.github.io/rn-file-toolkit/",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },