docs: 4.x documentation updates

Author: ian-wd

README.md

@@ -1,6 +1,8 @@
 # react-native-fs2
 _A fork of [react-native-fs](https://github.com/itinance/react-native-fs) with a smaller footprint and fixes due to the upstream library seemingly being abandoned._
 
+**Now powered by [Nitro Modules](https://github.com/mrousavy/nitro)** for superior performance and type safety! 🚀
+
 ### Why the fork?
 This library intentional or not has become critical to the success of our mobile applications. We've noticed a few things that led to this fork:
 
@@ -18,19 +20,42 @@ We debated a few paths, but we felt it best to fork the project and make some ma
 
 We will continue to support this library for as long as we use it.
 
+## Features
+
+- 🚀 **High Performance**: Powered by Nitro Modules with direct JSI bindings
+- 📁 **File System Operations**: Complete file system access (read, write, copy, move, etc.)
+- 🌊 **File Streaming** (Beta): Efficiently handle large files with streaming API
+- 📱 **MediaStore Support**: Android MediaStore integration for media files
+- ⬇️ **Downloads**: Background downloads with progress tracking
+- 🔒 **Type Safe**: Full TypeScript support with end-to-end type safety
+- 🎯 **Cross Platform**: iOS and Android support
+
 ### Installation
 ```bash
 npm i --save react-native-fs2
+# Peer dependency required
+npm i --save react-native-nitro-modules
 ```
 
 #### Supported React Native Versions
 | react-native-fs2 | react-native |
 |------------------|--------------|
+| 4.x (nitro)      | >=0.80       |
 | 3.0.x            | >=0.69       |
 
 ### Changelog
 Changes can be found in [CHANGELOG.md](CHANGELOG.md)
 
+### What's New in 4.x
+
+- **Nitro Modules Architecture**: Complete rewrite using Nitro Modules for superior performance
+- **File Streaming API**: New streaming capabilities for large file operations (see [FILE_STREAM.md](./docs/FILE_STREAM.md))
+- **Better Type Safety**: End-to-end type safety from TypeScript to native code
+- **ArrayBuffer Built-in**: Native ArrayBuffer support without additional dependencies
+- **Backward Compatible API**: Most existing code works without changes!
+
+> **Note**: v4.x requires `react-native-nitro-modules` as a peer dependency. See migration notes below.
+
 ## Usage
 ```ts
 import RNFS from 'react-native-fs2';
@@ -114,15 +139,15 @@ await RNFS.completeHandler('JobID')
 // readDir(dirPath: string): Promise<ReadDirItem[]>
 const dirItems = await RNFS.readDir('DirPath')
 ```
-* Retuns an `array` of `ReadDirItem` which are items that are present in the directory
+* Returns an `array` of `ReadDirItem` which are items that are present in the directory
 * `ReadDirItem`
-  * ctime: `Date | undefined` -> The creation date of the file (iOS only)
-  * mtime: `Date | undefined` -> The last modified date of the file
+  * ctime: `number | undefined` -> The creation timestamp in milliseconds (iOS only)
+  * mtime: `number` -> The last modified timestamp in milliseconds
   * name: `string` -> The name of the item
   * path: `string` -> The absolute path to the item
   * size: `number` -> Size in bytes
-  * isFile: () => `boolean` -> Is the file just a file?
-  * isDirectory: () => `boolean` -> Is the file a directory?
+  * isFile: `boolean` -> Is the item a file?
+  * isDirectory: `boolean` -> Is the item a directory?
 
 
 ### `readFile`
@@ -134,8 +159,7 @@ const fileData = await RNFS.readFile('DirPath', 'utf8')
 * Optionally includes `EncodingOrOptions` with values:
   * `'utf8'` (default) | `'base64'` (for binary files) | `'ascii'` | `'arraybuffer'`
   * ...fileoptions
-* Note: `arraybuffer` requires [react-native-blob-jsi-helper](https://github.com/mrousavy/react-native-blob-jsi-helper)
-  * `npm i react-native-blob-jsi-helper` or `yarn add react-native-blob-jsi-helper`
+* Note: `arraybuffer` support is built-in via Nitro Modules (no additional dependencies required)
 
 ### `read`
 ```ts
@@ -202,13 +226,13 @@ await RNFS.write('FileToWrite', 'ContentsToWrite', -1, 'utf8')
 // stat(filepath: string): Promise<StatResult>
 const fileStats = await RNFS.stat('FilePath')
 ```
-* Retuns an `array` of `StatResult` which are `statistics` of the `file`
+* Returns a `StatResult` object with statistics of the file
 * `StatResult`
   * path: `string` -> The same as filepath argument
-  * ctime: `date` -> The creation date of the file
-  * mtime: `date` -> The last modified date of the file
+  * ctime: `number` -> The creation timestamp in milliseconds
+  * mtime: `number` -> The last modified timestamp in milliseconds
   * size: `number` -> Size in bytes
-  * mode: `number` -> UNIX file mode
+  * mode: `number` -> UNIX file mode (iOS only)
   * originalFilepath: `string` -> Android: In case of content uri this is the pointed file path, otherwise is the same as path
   * isFile: () => `boolean` -> Is the file just a file?
   * isDirectory: () => `boolean` -> Is the file a directory?
@@ -278,6 +302,68 @@ await RNFS.scanFile('FilePath', Date, Date)
 ```
 * Scan the file using [Media Scanner](https://developer.android.com/reference/android/media/MediaScannerConnection).
 
+# File Streaming API (Beta)
+
+React-native-fs2 now provides powerful file streaming capabilities for efficiently reading and writing large files without loading entire content into memory.
+
+### `createReadStream`
+```ts
+import { createReadStream, listenToReadStreamData, listenToReadStreamProgress, listenToReadStreamEnd } from 'react-native-fs2';
+
+const stream = await createReadStream('/path/to/large-file.dat', {
+  bufferSize: 8192 // 8KB chunks
+});
+
+// Listen for data chunks
+const unsubData = listenToReadStreamData(stream.streamId, (event) => {
+  console.log(`Chunk ${event.chunk}: ${event.data.byteLength} bytes`);
+});
+
+// Listen for progress
+const unsubProgress = listenToReadStreamProgress(stream.streamId, (event) => {
+  console.log(`Progress: ${event.progress * 100}%`);
+});
+
+// Listen for completion
+const unsubEnd = listenToReadStreamEnd(stream.streamId, (event) => {
+  console.log('Stream finished');
+  unsubData();
+  unsubProgress();
+  unsubEnd();
+});
+
+await stream.start();
+```
+
+### `createWriteStream`
+```ts
+import { createWriteStream, listenToWriteStreamProgress, listenToWriteStreamFinish } from 'react-native-fs2';
+
+const stream = await createWriteStream('/path/to/output-file.dat', {
+  append: false,
+  createDirectories: true
+});
+
+// Listen for progress
+const unsubProgress = listenToWriteStreamProgress(stream.streamId, (event) => {
+  console.log(`Written: ${event.bytesWritten} bytes`);
+});
+
+// Listen for completion
+const unsubFinish = listenToWriteStreamFinish(stream.streamId, (event) => {
+  console.log('Write completed:', event.bytesWritten, 'bytes');
+  unsubProgress();
+  unsubFinish();
+});
+
+// Write data in chunks
+await stream.write(chunk1);
+await stream.write(chunk2);
+await stream.close();
+```
+
+**For complete streaming API documentation, see [FILE_STREAM.md](./docs/FILE_STREAM.md)**
+
 # MediaStore
 
 ### RNFS2 can now interact with the MediaStore on Android. This allows you to add, delete, and update media files in the MediaStore. 
@@ -433,3 +519,82 @@ type MediaStoreQueryResult = {
 #### iOS
  * `LibraryDirectoryPath` - Absolute path to [NSLibraryDirectory](https://developer.apple.com/documentation/foundation/nssearchpathdirectory/nslibrarydirectory)
  * `MainBundlePath` - Absolute path to main bundle directory.
+
+## Migrating from v3.x to v4.x
+
+The v4.x release brings significant improvements with minimal breaking changes. Most apps can upgrade with little to no code changes!
+
+### Installation
+
+1. **Install peer dependency:**
+```bash
+npm install react-native-nitro-modules
+# or
+yarn add react-native-nitro-modules
+```
+
+2. **Update react-native-fs2:**
+```bash
+npm install react-native-fs2@latest
+# or
+yarn add react-native-fs2@latest
+```
+
+### Breaking Changes
+
+#### Timestamps are now numbers
+The only significant breaking change is that timestamps are now returned as numbers (milliseconds since epoch) instead of Date objects:
+
+```typescript
+// v3.x
+const items = await RNFS.readDir(path);
+const date = items[0].mtime; // Date object
+
+// v4.x
+const items = await RNFS.readDir(path);
+const timestamp = items[0].mtime; // number
+const date = new Date(items[0].mtime); // Convert to Date if needed
+```
+
+This affects:
+- `readDir()` - `ctime` and `mtime` fields
+- `stat()` - `ctime` and `mtime` fields
+
+### What Still Works
+
+✅ **All core file operations** - No changes required:
+```typescript
+await RNFS.readFile(path, 'utf8');
+await RNFS.writeFile(path, content, 'utf8');
+await RNFS.copyFile(src, dest);
+await RNFS.moveFile(src, dest);
+await RNFS.unlink(path);
+// ... all other operations work the same!
+```
+
+✅ **Download API** - Backward compatible:
+```typescript
+const { jobId, promise } = RNFS.downloadFile({
+  fromUrl: url,
+  toFile: path,
+  begin: (res) => { },
+  progress: (res) => { }
+});
+```
+
+✅ **MediaStore** (Android) - Works the same
+
+### New Features to Explore
+
+Once migrated, you can optionally explore:
+
+- **File Streaming API**: For efficient large file operations (see [FILE_STREAM.md](./docs/FILE_STREAM.md))
+- **Better Performance**: Automatic via Nitro Modules architecture
+- **Enhanced Type Safety**: Full TypeScript support throughout
+
+### Need Help?
+
+If you encounter issues during migration:
+1. Check the [CHANGELOG.md](./CHANGELOG.md) for detailed changes
+2. Review [FILE_STREAM.md](./docs/FILE_STREAM.md) for streaming API
+3. Open an issue on [GitHub](https://github.com/sourcetoad/react-native-fs2/issues)

docs/FILE_STREAM.md

@@ -31,8 +31,8 @@ Creates a read stream for efficiently reading large files in chunks.
 ```typescript
 interface ReadStreamOptions {
   bufferSize?: number;      // Buffer size in bytes (default: 4096)
-  start?: bigint;           // Start position in bytes (default: 0)
-  end?: bigint;            // End position in bytes (default: file end)
+  start?: number;           // Start position in bytes (default: 0)
+  end?: number;             // End position in bytes (default: file end)
 }
 ```
 
@@ -93,20 +93,20 @@ function listenToReadStreamProgress(
 interface ReadStreamDataEvent {
   streamId: string;
   data: ArrayBuffer;     // Raw data chunk
-  chunk: bigint;         // Chunk number (0-based)
-  position: bigint;      // Current position in file
+  chunk: number;         // Chunk number (0-based)
+  position: number;      // Current position in file
 }
 
 interface ReadStreamProgressEvent {
   streamId: string;
-  bytesRead: bigint;     // Total bytes read so far
-  totalBytes: bigint;    // Total file size
+  bytesRead: number;     // Total bytes read so far
+  totalBytes: number;    // Total file size
   progress: number;      // Progress as percentage (0-100)
 }
 
 interface ReadStreamEndEvent {
   streamId: string;
-  bytesRead: bigint;     // Total bytes read
+  bytesRead: number;     // Total bytes read
   success: boolean;
 }
 
@@ -208,21 +208,24 @@ interface WriteStreamOptions {
 ```typescript
 interface WriteStreamHandle {
   streamId: string;
-  
+
   // Write data chunk to stream
   write(data: ArrayBuffer): Promise<void>;
-  
+
   // Flush any buffered data
   flush(): Promise<void>;
-  
+
   // Close the stream and finish writing
   close(): Promise<void>;
-  
+
   // Check if stream is active
   isActive(): Promise<boolean>;
-  
+
   // Get current write position
-  getPosition(): Promise<bigint>;
+  getPosition(): Promise<number>;
+
+  // End the stream (alias for close)
+  end(): Promise<void>;
 }
 ```
 
@@ -253,13 +256,13 @@ function listenToWriteStreamError(
 ```typescript
 interface WriteStreamProgressEvent {
   streamId: string;
-  bytesWritten: bigint;    // Total bytes written so far
-  lastChunkSize: bigint;   // Size of last written chunk
+  bytesWritten: number;    // Total bytes written so far
+  lastChunkSize: number;   // Size of last written chunk
 }
 
 interface WriteStreamFinishEvent {
   streamId: string;
-  bytesWritten: bigint;    // Total bytes written
+  bytesWritten: number;    // Total bytes written
   success: boolean;
 }