refactor: leverage arraybuffer on native read/write stream

Author: ian-wd

android/src/main/java/com/margelo/nitro/fs2/Fs2Stream.kt

@@ -161,7 +161,6 @@ class Fs2Stream(): HybridFs2StreamSpec() {
             if (state.job == null) {
                 state.job = streamScope.launch {
                     val bufferSize = state.options?.bufferSize ?: 8192
-                    val encoding = state.options?.encoding ?: Encoding.ARRAYBUFFER
                     val start = state.options?.start ?: 0L
                     val end = state.options?.end
                     var position = start
@@ -195,8 +194,7 @@ class Fs2Stream(): HybridFs2StreamSpec() {
                                             streamId = streamId,
                                             data = ArrayBuffer.copy(java.nio.ByteBuffer.wrap(data)),
                                             chunk = chunk,
-                                            position = position,
-                                            encoding = encoding
+                                            position = position
                                         )
                                     )
 
@@ -302,22 +300,6 @@ class Fs2Stream(): HybridFs2StreamSpec() {
         }
     }
 
-    override fun writeStringToStream(streamId: String, data: String): Promise<Unit> {
-        return Promise.async {
-            val impl = writeStreams[streamId] ?: throw Exception("ENOENT: No such write stream: $streamId")
-            if (!impl.state.isActive) throw Exception("EPIPE: Write stream is not active: $streamId")
-            val encoding = impl.state.options?.encoding ?: Encoding.UTF8
-            val bytes = when (encoding) {
-                Encoding.UTF8 -> data.toByteArray(Charsets.UTF_8)
-                Encoding.ASCII -> data.toByteArray(Charsets.US_ASCII)
-                Encoding.BASE64 -> android.util.Base64.decode(data, android.util.Base64.DEFAULT)
-                else -> data.toByteArray()
-            }
-            impl.queue.add(WriteRequest(bytes, isString = true))
-            impl.state.job?.let { if (!it.isActive) throw Exception("EPIPE: Write job is not active") }
-        }
-    }
-
     override fun flushWriteStream(streamId: String): Promise<Unit> {
         return Promise.async {
             val impl = writeStreams[streamId] ?: throw Exception("ENOENT: No such write stream: $streamId")

docs/FILE_STREAM.md

@@ -12,6 +12,8 @@ File streams are ideal for handling large files where loading entire content int
 - **Event-Driven**: Use Nitro callbacks for real-time progress updates
 - **Cross-Platform**: Consistent API across iOS and Android
 
+> **Note:** The stream API is now binary-only. All encoding/decoding (e.g., UTF-8, Base64) must be handled in JavaScript. Native code only receives and returns `ArrayBuffer`.
+
 ## Read Stream API
 
 ### `createReadStream(path: string, options?: ReadStreamOptions): Promise<ReadStreamHandle>`
@@ -29,12 +31,9 @@ Creates a read stream for efficiently reading large files in chunks.
 ```typescript
 interface ReadStreamOptions {
   bufferSize?: number;      // Buffer size in bytes (default: 4096)
-  encoding?: StreamEncoding; // 'utf8' | 'ascii' | 'base64' | 'arraybuffer' (default: 'arraybuffer')
   start?: bigint;           // Start position in bytes (default: 0)
   end?: bigint;            // End position in bytes (default: file end)
 }
-
-type StreamEncoding = 'utf8' | 'ascii' | 'base64' | 'arraybuffer';
 ```
 
 #### ReadStreamHandle
@@ -96,7 +95,6 @@ interface ReadStreamDataEvent {
   data: ArrayBuffer;     // Raw data chunk
   chunk: bigint;         // Chunk number (0-based)
   position: bigint;      // Current position in file
-  encoding: StreamEncoding;
 }
 
 interface ReadStreamProgressEvent {
@@ -122,39 +120,37 @@ interface ReadStreamErrorEvent {
 ### Read Stream Example
 
 ```typescript
-import { Fs2 } from 'react-native-fs2-nitro';
+import { Fs2, concatenateArrayBuffers, listenToReadStreamData, listenToReadStreamProgress, listenToReadStreamEnd, listenToReadStreamError } from 'react-native-fs2-nitro';
 
 async function readLargeFile() {
   try {
     // Create read stream
     const stream = await Fs2.createReadStream('/path/to/large-file.dat', {
-      bufferSize: 8192,     // 8KB chunks
-      encoding: 'arraybuffer'
+      bufferSize: 8192 // 8KB chunks
     });
 
     let totalData = new ArrayBuffer(0);
 
     // Listen for data chunks
-    const unsubscribeData = Fs2.listenToReadStreamData(
+    const unsubscribeData = listenToReadStreamData(
       stream.streamId,
       (event) => {
         console.log(`Received chunk ${event.chunk}, ${event.data.byteLength} bytes`);
-        
         // Accumulate data (for small files) or process chunk immediately
         totalData = concatenateArrayBuffers(totalData, event.data);
       }
     );
 
     // Listen for progress updates
-    const unsubscribeProgress = Fs2.listenToReadStreamProgress(
+    const unsubscribeProgress = listenToReadStreamProgress(
       stream.streamId,
       (event) => {
-        console.log(`Progress: ${event.progress.toFixed(1)}% (${event.bytesRead}/${event.totalBytes})`);
+        console.log(`Progress: ${(event.progress * 100).toFixed(1)}% (${event.bytesRead}/${event.totalBytes})`);
       }
     );
 
     // Listen for completion
-    const unsubscribeEnd = Fs2.listenToReadStreamEnd(
+    const unsubscribeEnd = listenToReadStreamEnd(
       stream.streamId,
       (event) => {
         console.log('Stream finished successfully');
@@ -165,7 +161,7 @@ async function readLargeFile() {
     );
 
     // Listen for errors
-    const unsubscribeError = Fs2.listenToReadStreamError(
+    const unsubscribeError = listenToReadStreamError(
       stream.streamId,
       (event) => {
         console.error('Stream error:', event.error);
@@ -202,7 +198,6 @@ Creates a write stream for efficiently writing large files in chunks.
 ```typescript
 interface WriteStreamOptions {
   append?: boolean;         // Append to existing file (default: false)
-  encoding?: StreamEncoding; // 'utf8' | 'ascii' | 'base64' | 'arraybuffer' (default: 'arraybuffer')
   bufferSize?: number;      // Internal buffer size (default: 4096)
   createDirectories?: boolean; // Create parent directories if needed (default: true)
 }
@@ -217,9 +212,6 @@ interface WriteStreamHandle {
   // Write data chunk to stream
   write(data: ArrayBuffer): Promise<void>;
 
-  // Write string data (when encoding is utf8 or base64)
-  writeString(data: string): Promise<void>;
-  
   // Flush any buffered data
   flush(): Promise<void>;
 
@@ -281,27 +273,26 @@ interface WriteStreamErrorEvent {
 ### Write Stream Example
 
 ```typescript
-import { Fs2 } from 'react-native-fs2-nitro';
+import { Fs2, listenToWriteStreamProgress, listenToWriteStreamFinish, listenToWriteStreamError } from 'react-native-fs2-nitro';
 
 async function writeLargeFile() {
   try {
     // Create write stream
     const stream = await Fs2.createWriteStream('/path/to/output-file.dat', {
       append: false,
-      encoding: 'binary',
       createDirectories: true
     });
 
     // Listen for progress
-    const unsubscribeProgress = Fs2.listenToWriteStreamProgress(
+    const unsubscribeProgress = listenToWriteStreamProgress(
       stream.streamId,
       (event) => {
         console.log(`Written: ${event.bytesWritten} bytes`);
       }
     );
 
     // Listen for completion
-    const unsubscribeFinish = Fs2.listenToWriteStreamFinish(
+    const unsubscribeFinish = listenToWriteStreamFinish(
       stream.streamId,
       (event) => {
         console.log('Write completed:', event.bytesWritten, 'bytes');
@@ -311,7 +302,7 @@ async function writeLargeFile() {
     );
 
     // Listen for errors
-    const unsubscribeError = Fs2.listenToWriteStreamError(
+    const unsubscribeError = listenToWriteStreamError(
       stream.streamId,
       (event) => {
         console.error('Write error:', event.error);
@@ -341,110 +332,45 @@ async function writeLargeFile() {
 
 ## Utility Functions
 
-### Text Processing with Streams
+### Text and Binary Processing with Streams
 
 ```typescript
-// Read text file in chunks with specific encoding
-async function readTextStream(filePath: string, encoding: 'utf8' = 'utf8') {
-  const stream = await Fs2.createReadStream(filePath, { encoding });
-  let content = '';
-
-  return new Promise<string>((resolve, reject) => {
-    const unsubscribeData = Fs2.listenToReadStreamData(stream.streamId, (event) => {
-      // Convert ArrayBuffer to string based on encoding
-      const chunk = arrayBufferToString(event.data, encoding);
-      content += chunk;
-    });
+import { readStream, writeStream } from 'react-native-fs2-nitro';
 
-    const unsubscribeEnd = Fs2.listenToReadStreamEnd(stream.streamId, () => {
-      unsubscribeData();
-      unsubscribeEnd();
-      resolve(content);
-    });
+// Read a file as a string (text mode)
+async function readTextFile(filePath: string, encoding: 'utf8' = 'utf8') {
+  const content = await readStream(filePath, encoding);
+  // content is a string
+}
 
-    const unsubscribeError = Fs2.listenToReadStreamError(stream.streamId, (event) => {
-      unsubscribeData();
-      unsubscribeEnd();
-      unsubscribeError();
-      reject(new Error(event.error));
-    });
+// Read a file as binary (default)
+async function readBinaryFile(filePath: string) {
+  const buffer = await readStream(filePath); // default is 'arraybuffer'
+  // buffer is an ArrayBuffer
+}
 
-    stream.start();
-  });
+// Write a string to a file (text mode)
+async function writeTextFile(filePath: string, text: string, encoding: 'utf8' = 'utf8') {
+  await writeStream(filePath, text, encoding);
 }
 
-// Write text with streaming
-async function writeTextStream(filePath: string, text: string, encoding: 'utf8' = 'utf8') {
-  const stream = await Fs2.createWriteStream(filePath, { encoding });
-  
-  const data = stringToArrayBuffer(text, encoding);
-  await stream.write(data);
-  await stream.close();
+// Write binary data to a file (default)
+async function writeBinaryFile(filePath: string, buffer: ArrayBuffer) {
+  await writeStream(filePath, buffer); // default is 'arraybuffer'
 }
 ```
 
 ### File Copy with Progress
 
 ```typescript
-async function copyFileWithProgress(
+import { copyFileWithProgress } from 'react-native-fs2-nitro';
+
+async function copyFileWithProgressExample(
   sourcePath: string,
   destPath: string,
   onProgress?: (progress: number) => void
 ) {
-  const readStream = await Fs2.createReadStream(sourcePath, { bufferSize: 16384 });
-  const writeStream = await Fs2.createWriteStream(destPath, { bufferSize: 16384 });
-
-  return new Promise<void>((resolve, reject) => {
-    let unsubscribeData: (() => void) | null = null;
-    let unsubscribeProgress: (() => void) | null = null;
-    let unsubscribeEnd: (() => void) | null = null;
-    let unsubscribeError: (() => void) | null = null;
-
-    const cleanup = () => {
-      unsubscribeData?.();
-      unsubscribeProgress?.();
-      unsubscribeEnd?.();
-      unsubscribeError?.();
-    };
-
-    // Forward read data to write stream
-    unsubscribeData = Fs2.listenToReadStreamData(readStream.streamId, async (event) => {
-      try {
-        await writeStream.write(event.data);
-      } catch (error) {
-        cleanup();
-        reject(error);
-      }
-    });
-
-    // Track progress
-    if (onProgress) {
-      unsubscribeProgress = Fs2.listenToReadStreamProgress(readStream.streamId, (event) => {
-        onProgress(event.progress);
-      });
-    }
-
-    // Handle completion
-    unsubscribeEnd = Fs2.listenToReadStreamEnd(readStream.streamId, async () => {
-      try {
-        await writeStream.close();
-        cleanup();
-        resolve();
-      } catch (error) {
-        cleanup();
-        reject(error);
-      }
-    });
-
-    // Handle errors
-    unsubscribeError = Fs2.listenToReadStreamError(readStream.streamId, (event) => {
-      cleanup();
-      reject(new Error(event.error));
-    });
-
-    // Start the copy
-    readStream.start();
-  });
+  await copyFileWithProgress(sourcePath, destPath, { bufferSize: 16384, onProgress });
 }
 ```
 
@@ -461,19 +387,7 @@ async function copyFileWithProgress(
 
 4. **Threading**: Stream operations run on background threads, keeping the UI responsive
 
-5. **Encoding**: Use 'arraybuffer' encoding for maximum performance when dealing with raw data
-
-## Platform Differences
-
-### iOS
-- Uses `NSInputStream` and `NSOutputStream` for efficient native streaming
-- Supports all encoding types natively
-- File system permissions handled automatically
-
-### Android  
-- Uses `FileInputStream` and `FileOutputStream` with buffer management
-- UTF-8 and Base64 encoding handled efficiently
-- Respects Android scoped storage requirements
+5. **Encoding**: All encoding/decoding is handled in JavaScript. Native code only deals with `ArrayBuffer`.
 
 ## Error Codes
 
@@ -501,13 +415,15 @@ ReactNativeBlobUtil.fs.readStream(path, encoding, bufferSize)
   });
 
 // fs2-nitro style  
-const stream = await Fs2.createReadStream(path, { encoding, bufferSize });
+const stream = await Fs2.createReadStream(path, { bufferSize });
 const unsubscribeData = Fs2.listenToReadStreamData(stream.streamId, event => { 
   /* handle event.data */ 
 });
+
 const unsubscribeEnd = Fs2.listenToReadStreamEnd(stream.streamId, () => { 
   /* handle end */ 
 });
+
 await stream.start();
 ```
 

ios/Fs2Stream.swift

@@ -144,7 +144,6 @@ class Fs2Stream: HybridFs2StreamSpec {
       state.isActive = true
 
       let bufferSize = Int(state.options?.bufferSize ?? 8192)
-      let encoding = state.options?.encoding ?? .arraybuffer
       let start = state.options?.start ?? 0
       let end = state.options?.end
       var position = start
@@ -181,7 +180,7 @@ class Fs2Stream: HybridFs2StreamSpec {
             let data = try state.fileHandle.read(upToCount: bytesToRead) ?? Data()
             if data.isEmpty { break }
             let arrayBuffer = try ArrayBufferHolder.copy(data: data)
-            self.readStreamDataListeners[streamId]?(ReadStreamDataEvent(streamId: streamId, data: arrayBuffer, chunk: chunk, position: position, encoding: encoding))
+            self.readStreamDataListeners[streamId]?(ReadStreamDataEvent(streamId: streamId, data: arrayBuffer, chunk: chunk, position: position))
             position += Int64(data.count)
             state.position = position
             bytesReadTotal += Int64(data.count)
@@ -267,25 +266,6 @@ class Fs2Stream: HybridFs2StreamSpec {
     }
   }
 
-  func writeStringToStream(streamId: String, data: String) throws -> NitroModules.Promise<Void> {
-    return Promise.async {
-      guard let state = self.writeStreams[streamId] else {
-        throw NSError(domain: "Fs2Stream", code: 0, userInfo: [NSLocalizedDescriptionKey: "ENOENT: No such write stream: \(streamId)"])
-      }
-      if !state.isActive { throw NSError(domain: "Fs2Stream", code: 0, userInfo: [NSLocalizedDescriptionKey: "EPIPE: Write stream is not active: \(streamId)"]) }
-      let encoding = state.options?.encoding ?? .utf8
-      let bytes: Data
-      switch encoding {
-      case .utf8: bytes = data.data(using: .utf8) ?? Data()
-      case .ascii: bytes = data.data(using: .ascii) ?? Data()
-      case .base64: bytes = Data(base64Encoded: data) ?? Data()
-      default: bytes = data.data(using: .utf8) ?? Data()
-      }
-      state.writeBufferContinuation?.yield((bytes, true))
-      if let task = state.task, task.isCancelled { throw NSError(domain: "Fs2Stream", code: 0, userInfo: [NSLocalizedDescriptionKey: "EPIPE: Write job is not active"]) }
-    }
-  }
-
   func flushWriteStream(streamId: String) throws -> NitroModules.Promise<Void> {
     return Promise.async {
       guard let state = self.writeStreams[streamId] else {