feat: return ArrayBuffer from downloadFile

[patrickkabwe]

Summary

• adds output?: 'file' | 'arrayBuffer' to NitroDownloadOptions
• changes downloadFile to return Promise<NitroFile | ArrayBuffer>
• keeps default behavior returning NitroFile
• returns a zero-copy ArrayBuffer for output: 'arrayBuffer' by memory-mapping the saved file on iOS and Android
• regenerates Nitrogen bindings for the new output enum and result union

New usage

const result = await NitroFS.downloadFile({
  url: 'https://example.com/files/document.pdf',
  destinationPath: `${NitroFS.DOWNLOAD_DIR}/document.pdf`,
  output: 'arrayBuffer',
})

if (!(result instanceof ArrayBuffer)) {
  throw new Error('Expected ArrayBuffer')
}

const bytes = new Uint8Array(result)
console.log('Downloaded byte length:', bytes.byteLength)

Default usage still returns file metadata:

const result = await NitroFS.downloadFile({
  url: 'https://example.com/files/document.pdf',
  destinationPath: `${NitroFS.DOWNLOAD_DIR}/document.pdf`,
})

if (result instanceof ArrayBuffer) {
  throw new Error('Expected NitroFile')
}

console.log(result.name, result.path, result.mimeType)

Verification

• rtk bunx nitrogen --logLevel="debug"
• rtk node post-script.js
• rtk proxy git diff --check
• rtk bun run typecheck
• rtk bun run build

Native build notes

• Android Gradle compile did not complete in this environment; it stalled during React Native Gradle plugin setup and was interrupted.
• iOS xcodebuild failed before reaching NitroFS because ReactCodegen generated files were missing under example/ios/build/generated/ios/ReactCodegen.

[coderabbitai]

Warning

Review limit reached

Next included review available in 32 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d21bbcd9-fbd2-47c2-a117-b08d7bfaa413

📥 Commits

Reviewing files that changed from the base of the PR and between c8adab6 and f86f74d.

📒 Files selected for processing (2)

• ios/HybridNitroFs.swift
• ios/NitroFSFileDownloader.swift

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c47ac31a-5144-47e5-bede-86905b0cb3db

📥 Commits

Reviewing files that changed from the base of the PR and between bfcd4ac and c8adab6.

⛔ Files ignored due to path filters (25)

• nitrogen/generated/android/NitroFS+autolinking.cmake is excluded by !**/generated/**
• nitrogen/generated/android/c++/JHybridNitroFSSpec.cpp is excluded by !**/generated/**
• nitrogen/generated/android/c++/JHybridNitroFSSpec.hpp is excluded by !**/generated/**
• nitrogen/generated/android/c++/JNitroDownloadOptions.hpp is excluded by !**/generated/**
• nitrogen/generated/android/c++/JNitroDownloadOutput.hpp is excluded by !**/generated/**
• nitrogen/generated/android/c++/JNitroDownloadResult.cpp is excluded by !**/generated/**
• nitrogen/generated/android/c++/JNitroDownloadResult.hpp is excluded by !**/generated/**
• nitrogen/generated/android/kotlin/com/margelo/nitro/nitrofs/HybridNitroFSSpec.kt is excluded by !**/generated/**
• nitrogen/generated/android/kotlin/com/margelo/nitro/nitrofs/NitroDownloadOptions.kt is excluded by !**/generated/**
• nitrogen/generated/android/kotlin/com/margelo/nitro/nitrofs/NitroDownloadOutput.kt is excluded by !**/generated/**
• nitrogen/generated/android/kotlin/com/margelo/nitro/nitrofs/NitroDownloadResult.kt is excluded by !**/generated/**
• nitrogen/generated/ios/NitroFS-Swift-Cxx-Bridge.cpp is excluded by !**/generated/**
• nitrogen/generated/ios/NitroFS-Swift-Cxx-Bridge.hpp is excluded by !**/generated/**
• nitrogen/generated/ios/NitroFS-Swift-Cxx-Umbrella.hpp is excluded by !**/generated/**
• nitrogen/generated/ios/c++/HybridNitroFSSpecSwift.hpp is excluded by !**/generated/**
• nitrogen/generated/ios/swift/Func_void_NitroFile.swift is excluded by !**/generated/**
• nitrogen/generated/ios/swift/Func_void_std__variant_std__shared_ptr_ArrayBuffer___NitroFile_.swift is excluded by !**/generated/**
• nitrogen/generated/ios/swift/HybridNitroFSSpec.swift is excluded by !**/generated/**
• nitrogen/generated/ios/swift/HybridNitroFSSpec_cxx.swift is excluded by !**/generated/**
• nitrogen/generated/ios/swift/NitroDownloadOptions.swift is excluded by !**/generated/**
• nitrogen/generated/ios/swift/NitroDownloadOutput.swift is excluded by !**/generated/**
• nitrogen/generated/ios/swift/NitroDownloadResult.swift is excluded by !**/generated/**
• nitrogen/generated/shared/c++/HybridNitroFSSpec.hpp is excluded by !**/generated/**
• nitrogen/generated/shared/c++/NitroDownloadOptions.hpp is excluded by !**/generated/**
• nitrogen/generated/shared/c++/NitroDownloadOutput.hpp is excluded by !**/generated/**

📒 Files selected for processing (14)

• README.md
• android/src/main/java/com/nitrofs/File+toMappedArrayBuffer.kt
• android/src/main/java/com/nitrofs/FileDownloader.kt
• android/src/main/java/com/nitrofs/HybridNitroFS.kt
• android/src/main/java/com/nitrofs/NitroFSImpl.kt
• example/src/hooks/use-file-system.ts
• ios/ArrayBuffer+mapFile.swift
• ios/HybridNitroFs.swift
• ios/NitroFSFileDownloader.swift
• ios/NitroFSImpl.swift
• src/specs/nitro-fs.nitro.ts
• src/type.ts
• tsconfig.type-tests.json
• type-tests/download-file-arraybuffer.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The download API adds an optional output mode for file or ArrayBuffer results. Android and iOS implement ArrayBuffer downloads through memory-mapped files. TypeScript declarations, documentation, examples, and type tests reflect the new result union.

Changes

Download output selection

Layer / File(s)	Summary
Public download contract src/type.ts, src/specs/nitro-fs.nitro.ts	The API adds NitroDownloadOutput, the optional output setting, and the NitroDownloadResult union.
Android download results android/src/main/java/com/nitrofs/*	Android maps downloaded files into ArrayBuffer values when requested and propagates NitroDownloadResult through the native API.
iOS download results ios/ArrayBuffer+mapFile.swift, ios/NitroFSFileDownloader.swift, ios/NitroFSImpl.swift, ios/HybridNitroFs.swift	iOS adds private file mapping, selects the requested output, and updates downloader and bridge return types.
Documentation and type validation README.md, example/src/hooks/use-file-system.ts, type-tests/*, tsconfig.type-tests.json	Documentation and examples describe both output modes. Type tests validate the result contract and narrowing behavior.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to c8ada

This change adds an opt-in ArrayBuffer download result while preserving the default file-metadata behavior. No actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant NitroFS
  participant PlatformDownloader
  participant FileSystem
  participant ArrayBuffer

  Client->>NitroFS: downloadFile(options)
  NitroFS->>PlatformDownloader: download with output mode
  PlatformDownloader->>FileSystem: save downloaded file
  alt output is arrayBuffer
    PlatformDownloader->>ArrayBuffer: map saved file
    ArrayBuffer-->>PlatformDownloader: ArrayBuffer result
  else output is file or unset
    FileSystem-->>PlatformDownloader: NitroFile result
  end
  PlatformDownloader-->>NitroFS: NitroDownloadResult
  NitroFS-->>Client: Promise result

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.56% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 18 functions across 12 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main API change: downloadFile can return an ArrayBuffer. It is concise and directly related to the pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 5.56% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 18 functions across 12 files. (2 skipped: 2 unsupported.)

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/download-file-arraybuffer

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}