react-native-buffered-blob 1.0.0

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "react-native-buffered-blob",
+  "version": "1.0.0",
+  "description": "No more OOM, just use buffered-blob",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "react-native-buffered-blob.podspec",
+    "react-native.config.js",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "prepare": "bob build",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "release": "release-it"
+  },
+  "codegenConfig": {
+    "name": "BufferedBlobSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.bufferedblob"
+    }
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android",
+    "blob",
+    "file"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/l2hyunwoo/react-native-nitro-blob.git",
+    "directory": "packages/react-native-buffered-blob"
+  },
+  "author": "HyunWoo Lee <l2hyunwoo@gmail.com> (https://github.com/l2hyunwoo)",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "*",
+    "react-native": ">=0.76.0"
+  },
+  "devDependencies": {
+    "react": "19.2.0",
+    "react-native": "0.83.0",
+    "react-native-builder-bob": "^0.40.18",
+    "typescript": "^5.9.2"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore: release react-native-buffered-blob ${version}",
+      "tagName": "react-native-buffered-blob@${version}",
+      "requireCleanWorkingDir": true
+    },
+    "npm": {
+      "publish": true,
+      "publishPath": "."
+    },
+    "github": {
+      "release": true,
+      "releaseName": "react-native-buffered-blob@${version}"
+    },
+    "hooks": {
+      "before:init": [
+        "yarn prepare"
+      ],
+      "after:bump": "yarn prepare"
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  }
+}

package/react-native-buffered-blob.podspec

@@ -0,0 +1,37 @@
+require "json"
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "react-native-buffered-blob"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["repository"]["url"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+  s.platforms    = { :ios => '15.1' }
+  s.source       = { :git => package["repository"]["url"], :tag => s.version }
+  s.source_files = [
+    "ios/**/*.{h,m,mm}",
+    "cpp/**/*.{h,hpp,cpp}",
+  ]
+
+  # Exclude Android-only files from the iOS build.
+  s.exclude_files = [
+    "cpp/jni_onload.cpp",
+    "cpp/AndroidPlatformBridge.{h,cpp}",
+  ]
+
+  # Keep C++ headers out of the modulemap so the Clang module builder
+  # does not try to parse them in C mode (which cannot resolve C++
+  # standard library includes like <functional>).
+  s.private_header_files = [
+    "cpp/**/*.{h,hpp}",
+    "ios/BufferedBlobStreamingBridge.h",
+  ]
+
+  s.pod_target_xcconfig = {
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++20",
+  }
+
+  install_modules_dependencies(s)
+end

package/react-native.config.js

@@ -0,0 +1,10 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        componentDescriptors: [],
+        cmakeListsPath: '../cpp/CMakeLists.txt',
+      },
+    },
+  },
+};

package/src/AGENTS.md

@@ -0,0 +1,70 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-02-15 -->
+
+# src/
+
+TypeScript API layer: Turbo Module spec, native module interface, streaming proxy, and high-level file operations.
+
+## Purpose
+
+Provides the JavaScript interface to the native BufferedBlob module:
+- **Turbo Module specification** (NativeBufferedBlob.ts) — codegen input for handle factories and FS ops
+- **Streaming proxy** (module.ts) — JSI HostObject accessor, install() wiring
+- **Type wrappers** (types.ts) — BlobReader/BlobWriter interfaces with property proxying
+- **Error handling** (errors.ts) — ErrorCode enum and wrapError() utility
+- **Paths** (paths.ts) — Dirs constants and path utilities
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `NativeBufferedBlob.ts` | Turbo Module spec: install(), handle factories, FS ops, hashFile. Codegen input. |
+| `module.ts` | NativeModule (TurboModuleRegistry), StreamingProxy interface, getStreamingProxy() |
+| `types.ts` | HashAlgorithm, FileType enums; FileInfo, BlobReader, BlobWriter interfaces; wrapReader/wrapWriter |
+| `errors.ts` | BlobError class, ErrorCode enum, wrapError() helper |
+| `paths.ts` | Dirs constants (documentDir, cacheDir, tempDir, downloadDir); join(), dirname(), basename(), extname() |
+| `index.ts` | Barrel exports for public API |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `api/` | High-level file operations, download, hashing, streaming wrappers |
+
+## For AI Agents
+
+### Working In This Directory
+
+1. **Turbo Module spec**: Changes to `NativeBufferedBlob.ts` trigger codegen. After editing, run `yarn prepare` to regenerate native module headers.
+2. **Streaming proxy access**: `getStreamingProxy()` returns the JSI HostObject installed by native code. Always call `NativeModule.install()` first (done in module.ts).
+3. **Handle pattern**: Turbo Module returns numeric handles. Pass to streaming proxy methods. Always close handles to release native resources.
+4. **Type safety**: Use strict TypeScript. BlobReader/BlobWriter are interface wrappers; do NOT spread HostObject properties (getters would be lost).
+5. **Error propagation**: Catch errors from native calls; use `wrapError()` to normalize error messages.
+
+### Testing Requirements
+
+- **Type checking**: Verify no TypeScript errors in strict mode
+- **Module loading**: Verify `install()` succeeds and JSI HostObject is wired
+- **Handle cleanup**: Verify handles are closed; no dangling native resources
+- **Error cases**: Test file not found, invalid paths, invalid buffer sizes, cancelled operations
+
+### Common Patterns
+
+1. **Create reader**: `const handle = NativeModule.openRead(path, bufferSize)` -> `const reader = wrapReader(handle, proxy)` -> `reader.readNextChunk()` -> `reader.close()`
+2. **Create writer**: `const handle = NativeModule.openWrite(path, append)` -> `const writer = wrapWriter(handle, proxy)` -> `writer.write(data)` -> `writer.flush()` -> `writer.close()`
+3. **File ops**: `exists()`, `stat()`, `mkdir()`, `ls()`, `cp()`, `mv()`, `unlink()` all return Promises
+4. **Hash file**: `hashFile(path, 'sha256' | 'md5')` streams file without loading into memory
+5. **Download with progress**: Use `download({ url, destPath, onProgress })` API; streaming proxy handles details
+
+## Dependencies
+
+### Internal
+- Turbo Module spec generated from `NativeBufferedBlob.ts` at build time
+- `module.ts` calls `install()` on first import (side effect)
+- `api/` layer depends on NativeModule and getStreamingProxy()
+
+### External
+- **React Native** >= 0.76.0 (TurboModuleRegistry, JSI)
+- **TypeScript** ^5.9.2 (type checking, codegen)
+
+<!-- MANUAL: Document API changes, Turbo Module version bumps, deprecations -->

package/src/NativeBufferedBlob.ts

@@ -0,0 +1,54 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  // Called once to install JSI HostObject on global.__BufferedBlobStreaming
+  install(): boolean;
+
+  // --- Stream Handle Factories ---
+  // Return numeric handle IDs that reference native objects in an internal registry.
+  // The handle IDs are passed to the JSI HostObject for streaming operations.
+  openRead(path: string, bufferSize: number): number;
+  openWrite(path: string, append: boolean): number;
+  createDownload(url: string, destPath: string, headers: Object): number;
+
+  // --- Handle Cleanup ---
+  // Close a handle by ID. Safe to call multiple times.
+  closeHandle(handleId: number): void;
+
+  // --- File System Operations ---
+  exists(path: string): Promise<boolean>;
+  stat(path: string): Promise<{
+    path: string;
+    name: string;
+    size: number;
+    type: string;
+    lastModified: number;
+  }>;
+  unlink(path: string): Promise<void>;
+  mkdir(path: string): Promise<void>;
+  ls(path: string): Promise<
+    Array<{
+      path: string;
+      name: string;
+      size: number;
+      type: string;
+      lastModified: number;
+    }>
+  >;
+  cp(srcPath: string, destPath: string): Promise<void>;
+  mv(srcPath: string, destPath: string): Promise<void>;
+
+  // --- Hashing ---
+  hashFile(path: string, algorithm: string): Promise<string>;
+
+  // --- Constants ---
+  getConstants(): {
+    documentDir: string;
+    cacheDir: string;
+    tempDir: string;
+    downloadDir: string;
+  };
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('BufferedBlob');

package/src/api/AGENTS.md

@@ -0,0 +1,62 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-02-15 -->
+
+# src/api/
+
+High-level convenience APIs for file operations, streaming, hashing, and downloads.
+
+## Purpose
+
+Provide idiomatic TypeScript wrappers around Turbo Module calls and JSI HostObject streaming:
+- **File operations**: exists, stat, mkdir, ls, cp, mv, unlink
+- **Streaming**: readFile (deprecated), writeFile (deprecated)
+- **Hashing**: hashFile with streaming (SHA256, MD5)
+- **Downloads**: download with progress callback
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `fileOps.ts` | FS operations: exists, stat, mkdir, ls, cp, mv, unlink. All return Promises. |
+| `hash.ts` | hashFile(path, algorithm) → Promise<string>. Streams file; supports 'sha256', 'md5'. |
+| `download.ts` | download(options) → Promise<void>. Returns DownloadOptions interface, handles progress callback. |
+| `readFile.ts` | DEPRECATED: createReader(path, bufferSize) → BlobReader. Use openRead() + wrapReader() directly. |
+| `writeFile.ts` | DEPRECATED: createWriter(path, append) → BlobWriter. Use openWrite() + wrapWriter() directly. |
+
+## For AI Agents
+
+### Working In This Directory
+
+1. **File operations**: All async. Return Promises that resolve/reject with platform-specific error codes.
+2. **Streaming shortcuts**: readFile/writeFile are deprecated convenience wrappers. New code should use `openRead()` + `wrapReader()` directly for explicit handle management.
+3. **Download pattern**: `download()` creates handle, calls JSI streaming startDownload, manages progress callback, cleans up handle in finally block.
+4. **Error handling**: Use `wrapError()` from parent module to normalize native errors.
+5. **Handle lifecycle**: Always close streaming handles (readFile/writeFile do this implicitly; direct handle usage requires explicit close).
+
+### Testing Requirements
+
+- **File ops**: Create temp files, test exists/stat/mkdir/ls/cp/mv/unlink
+- **Hashing**: Verify hash output against known digests (sha256, md5)
+- **Download**: Test with HTTP server, verify progress callback fires, verify file written
+- **Error cases**: Test file not found, permission denied, invalid paths, cancelled downloads
+
+### Common Patterns
+
+1. **Check file exists**: `const exists = await exists(path)`
+2. **Get file info**: `const info = await stat(path)` → {path, name, size, type, lastModified}
+3. **List directory**: `const files = await ls(dirPath)` → FileInfo[]
+4. **Copy file**: `await cp(srcPath, destPath)`
+5. **Hash file**: `const hash = await hashFile(path, 'sha256')`
+6. **Download with progress**: `await download({ url, destPath, headers: {}, onProgress: (p) => console.log(p.progress) })`
+
+## Dependencies
+
+### Internal
+- `../module.ts` — NativeModule, getStreamingProxy()
+- `../types.ts` — BlobReader, BlobWriter, FileInfo, DownloadProgress, HashAlgorithm
+- `../errors.ts` — wrapError()
+
+### External
+- **React Native** >= 0.76.0 (TurboModuleRegistry for NativeModule calls)
+
+<!-- MANUAL: Document deprecated APIs, migration guides for readFile/writeFile users -->

package/src/api/download.ts

@@ -0,0 +1,46 @@
+import { NativeModule, getStreamingProxy } from '../module';
+import { wrapError } from '../errors';
+import type { DownloadProgress } from '../types';
+
+export interface DownloadOptions {
+  url: string;
+  destPath: string;
+  headers?: Record<string, string>;
+  onProgress?: (progress: DownloadProgress) => void;
+}
+
+export interface DownloadHandle {
+  promise: Promise<void>;
+  cancel: () => void;
+}
+
+export function download(options: DownloadOptions): DownloadHandle {
+  const { url, destPath, headers = {}, onProgress } = options;
+
+  try {
+    const handleId = NativeModule.createDownload(url, destPath, headers);
+    const streaming = getStreamingProxy();
+
+    const progressCallback = onProgress
+      ? (bytesDownloaded: number, totalBytes: number, progress: number) => {
+          onProgress({ bytesDownloaded, totalBytes, progress });
+        }
+      : (_b: number, _t: number, _p: number) => {};
+
+    const promise = (async () => {
+      try {
+        await streaming.startDownload(handleId, progressCallback);
+      } finally {
+        NativeModule.closeHandle(handleId);
+      }
+    })();
+
+    const cancel = () => {
+      streaming.cancelDownload(handleId);
+    };
+
+    return { promise, cancel };
+  } catch (e) {
+    throw wrapError(e, destPath);
+  }
+}

package/src/api/fileOps.ts

@@ -0,0 +1,83 @@
+import { NativeModule } from '../module';
+import { wrapError } from '../errors';
+import type { FileInfo } from '../types';
+import { FileType } from '../types';
+
+function toFileType(raw: string): FileType {
+  const values: string[] = Object.values(FileType);
+  return values.includes(raw) ? (raw as FileType) : FileType.UNKNOWN;
+}
+
+function mapFileInfo(raw: {
+  path: string;
+  name: string;
+  size: number;
+  type: string;
+  lastModified: number;
+}): FileInfo {
+  return {
+    path: raw.path,
+    name: raw.name,
+    size: raw.size,
+    type: toFileType(raw.type),
+    lastModified: raw.lastModified,
+  };
+}
+
+export async function exists(path: string): Promise<boolean> {
+  try {
+    return await NativeModule.exists(path);
+  } catch (e) {
+    throw wrapError(e, path);
+  }
+}
+
+export async function stat(path: string): Promise<FileInfo> {
+  try {
+    const raw = await NativeModule.stat(path);
+    return mapFileInfo(raw);
+  } catch (e) {
+    throw wrapError(e, path);
+  }
+}
+
+export async function unlink(path: string): Promise<void> {
+  try {
+    await NativeModule.unlink(path);
+  } catch (e) {
+    throw wrapError(e, path);
+  }
+}
+
+export async function mkdir(path: string): Promise<void> {
+  try {
+    await NativeModule.mkdir(path);
+  } catch (e) {
+    throw wrapError(e, path);
+  }
+}
+
+export async function ls(path: string): Promise<FileInfo[]> {
+  try {
+    const rawList = await NativeModule.ls(path);
+    return rawList.map(mapFileInfo);
+  } catch (e) {
+    throw wrapError(e, path);
+  }
+}
+
+export async function cp(srcPath: string, destPath: string): Promise<void> {
+  try {
+    await NativeModule.cp(srcPath, destPath);
+  } catch (e) {
+    throw wrapError(e, srcPath);
+  }
+}
+
+export async function mv(srcPath: string, destPath: string): Promise<void> {
+  try {
+    await NativeModule.mv(srcPath, destPath);
+  } catch (e) {
+    throw wrapError(e, srcPath);
+  }
+}

package/src/api/hash.ts

@@ -0,0 +1,14 @@
+import { NativeModule } from '../module';
+import { wrapError } from '../errors';
+import { HashAlgorithm } from '../types';
+
+export async function hashFile(
+  path: string,
+  algorithm: HashAlgorithm = HashAlgorithm.SHA256
+): Promise<string> {
+  try {
+    return await NativeModule.hashFile(path, algorithm);
+  } catch (e) {
+    throw wrapError(e, path);
+  }
+}

package/src/api/readFile.ts

@@ -0,0 +1,37 @@
+import { NativeModule, getStreamingProxy } from '../module';
+import { wrapError, BlobError, ErrorCode } from '../errors';
+import { wrapReader } from '../wrappers';
+import type { BlobReader } from '../types';
+
+const DEFAULT_BUFFER_SIZE = 65536; // 64KB
+
+export function createReader(
+  path: string,
+  bufferSize: number = DEFAULT_BUFFER_SIZE
+): BlobReader {
+  try {
+    if (
+      !Number.isFinite(bufferSize) ||
+      bufferSize < 4096 ||
+      bufferSize > 4194304
+    ) {
+      throw new BlobError(
+        ErrorCode.INVALID_ARGUMENT,
+        `bufferSize must be between 4096 and 4194304, got ${bufferSize}`,
+        path
+      );
+    }
+    const handleId = NativeModule.openRead(path, bufferSize);
+    if (handleId < 0) {
+      throw new BlobError(
+        ErrorCode.IO_ERROR,
+        'Failed to open file for reading',
+        path
+      );
+    }
+    const streaming = getStreamingProxy();
+    return wrapReader(handleId, streaming);
+  } catch (e) {
+    throw wrapError(e, path);
+  }
+}

package/src/api/writeFile.ts

@@ -0,0 +1,24 @@
+import { NativeModule, getStreamingProxy } from '../module';
+import { wrapError, BlobError, ErrorCode } from '../errors';
+import { wrapWriter } from '../wrappers';
+import type { BlobWriter } from '../types';
+
+export function createWriter(
+  path: string,
+  append: boolean = false
+): BlobWriter {
+  try {
+    const handleId = NativeModule.openWrite(path, append);
+    if (handleId < 0) {
+      throw new BlobError(
+        ErrorCode.IO_ERROR,
+        'Failed to open file for writing',
+        path
+      );
+    }
+    const streaming = getStreamingProxy();
+    return wrapWriter(handleId, streaming);
+  } catch (e) {
+    throw wrapError(e, path);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,50 @@
+export enum ErrorCode {
+  FILE_NOT_FOUND = 'FILE_NOT_FOUND',
+  PERMISSION_DENIED = 'PERMISSION_DENIED',
+  FILE_ALREADY_EXISTS = 'FILE_ALREADY_EXISTS',
+  NOT_A_FILE = 'NOT_A_FILE',
+  NOT_A_DIRECTORY = 'NOT_A_DIRECTORY',
+  DIRECTORY_NOT_EMPTY = 'DIRECTORY_NOT_EMPTY',
+  IO_ERROR = 'IO_ERROR',
+  INVALID_ARGUMENT = 'INVALID_ARGUMENT',
+  DOWNLOAD_FAILED = 'DOWNLOAD_FAILED',
+  DOWNLOAD_CANCELLED = 'DOWNLOAD_CANCELLED',
+  READER_CLOSED = 'READER_CLOSED',
+  WRITER_CLOSED = 'WRITER_CLOSED',
+  UNKNOWN = 'UNKNOWN',
+}
+
+export class BlobError extends Error {
+  public readonly code: ErrorCode;
+  public readonly path?: string;
+
+  constructor(code: ErrorCode, message: string, path?: string) {
+    super(message);
+    this.name = 'BlobError';
+    this.code = code;
+    this.path = path;
+    Object.setPrototypeOf(this, BlobError.prototype);
+  }
+}
+
+/**
+ * Parse native error with format "[ERROR_CODE] message" into BlobError.
+ */
+export function wrapError(e: unknown, path?: string): BlobError {
+  if (e instanceof BlobError) {
+    return e;
+  }
+
+  const message = e instanceof Error ? e.message : String(e);
+  const match = /^\[([A-Z_]+)\]\s*(.*)$/.exec(message);
+
+  if (match) {
+    const [, code, msg] = match;
+    const errorCode = Object.values(ErrorCode).includes(code as ErrorCode)
+      ? (code as ErrorCode)
+      : ErrorCode.UNKNOWN;
+    return new BlobError(errorCode, msg || message, path);
+  }
+
+  return new BlobError(ErrorCode.UNKNOWN, message, path);
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+// Errors
+export { ErrorCode, BlobError, wrapError } from './errors';
+
+// Paths
+export { Dirs, join, dirname, basename, extname } from './paths';
+
+// Types
+export type {
+  FileInfo,
+  DownloadProgress,
+  BlobReader,
+  BlobWriter,
+} from './types';
+export { HashAlgorithm, FileType } from './types';
+
+// API - Streaming
+export { createReader } from './api/readFile';
+export { createWriter } from './api/writeFile';
+
+// API - File Operations
+export { exists, stat, unlink, mkdir, ls, cp, mv } from './api/fileOps';
+
+// API - Hashing
+export { hashFile } from './api/hash';
+
+// API - Download
+export { download } from './api/download';
+export type { DownloadOptions, DownloadHandle } from './api/download';

package/src/module.ts

@@ -0,0 +1,48 @@
+import NativeModule from './NativeBufferedBlob';
+
+// Install JSI HostObject on first import
+const installed = NativeModule.install();
+if (!installed) {
+  throw new Error(
+    '[BufferedBlob] Failed to install JSI streaming bridge. Ensure the native module is linked.'
+  );
+}
+
+export interface StreamingProxy {
+  readNextChunk(handleId: number): Promise<ArrayBuffer | null>;
+  write(handleId: number, data: ArrayBuffer): Promise<number>;
+  flush(handleId: number): Promise<void>;
+  close(handleId: number): void;
+  startDownload(
+    handleId: number,
+    onProgress: (
+      bytesDownloaded: number,
+      totalBytes: number,
+      progress: number
+    ) => void
+  ): Promise<void>;
+  cancelDownload(handleId: number): void;
+  getReaderInfo(handleId: number): {
+    fileSize: number;
+    bytesRead: number;
+    isEOF: boolean;
+  };
+  getWriterInfo(handleId: number): { bytesWritten: number };
+}
+
+declare global {
+  var __BufferedBlobStreaming: StreamingProxy | undefined;
+}
+
+// Access the JSI HostObject installed by native
+function getStreamingProxy(): StreamingProxy {
+  const proxy = globalThis.__BufferedBlobStreaming;
+  if (!proxy) {
+    throw new Error(
+      '[BufferedBlob] Streaming proxy not available. Make sure install() was called.'
+    );
+  }
+  return proxy as StreamingProxy;
+}
+
+export { NativeModule, getStreamingProxy };