react-native-nitro-buffer

A high-performance, Node.js compatible Buffer implementation for React Native, powered by Nitro Modules and C++.

🚀 Features

• ⚡️ Blazing Fast: Implemented in C++ using Nitro Modules for maximum performance.
• ✅ Node.js Compatible: Drop-in replacement for the standard Node.js Buffer API.
• 🔒 Type Safe: Written in TypeScript with full type definitions.
• 📦 Zero Dependencies: Lightweight and efficient.
• 📱 Cross Platform: Works flawlessly on iOS and Android.

🏎️ Performance

react-native-nitro-buffer is significantly faster than other Buffer implementations for React Native.

Device: iPad Air 5 (M1) - Physical Device

| Operation | Nitro Buffer | Competitor (Craftz) | Improvement | |:---|:---:|:---:|:---:| | fill(0) | 0.019ms | 10.37ms | ~545x 🚀 | | write(utf8) | 2.47ms | 212.04ms | ~85x 🚀 | | toString(utf8) | 0.89ms | 169.16ms | ~190x 🚀 | | toString(base64) | 0.69ms | 3.40ms | ~4.9x 🚀 | | from(base64) | 1.40ms | 146.56ms | ~104x 🚀 | | toString(hex) | 4.85ms | 57.34ms | ~11.8x 🚀 | | from(hex) | 11.06ms | 138.04ms | ~12.5x 🚀 | | btoa(1MB) | 3.00ms | 45.90ms | ~15.3x 🚀 | | atob(1MB) | 5.12ms | 149.73ms | ~29.2x 🚀 | | alloc(1MB) | 0.33ms | 0.09ms | 0.27x |

Device: iPhone 16 Pro Simulator (Mac mini M4)

| Operation | Nitro Buffer | Competitor (Craftz) | Improvement | |:---|:---:|:---:|:---:| | fill(0) | 0.015ms | 13.78ms | ~918x 🚀 | | write(utf8) | 4.27ms | 163.46ms | ~38x 🚀 | | toString(utf8) | 0.93ms | 141.56ms | ~152x 🚀 | | toString(base64) | 1.71ms | 4.71ms | ~3x 🚀 | | from(base64) | 16.45ms | 104.67ms | ~6x 🚀 | | toString(hex) | 4.89ms | 43.46ms | ~9x 🚀 | | from(hex) | 17.93ms | 95.00ms | ~5x 🚀 | | btoa(1MB) | 1.13ms | 34.87ms | ~31x 🚀 | | atob(1MB) | 2.18ms | 91.41ms | ~42x 🚀 | | alloc(1MB) | 0.18ms | 0.03ms | 0.16x |

> Benchmarks averaged over 50 iterations on 1MB Buffer operations.

[!NOTE] About alloc Performance: The slight difference in allocation time (~0.3ms) is due to the overhead of initializing the ES6 Class structure (Object.setPrototypeOf), which provides a cleaner and safer type inheritance model compared to the functional mixin approach. This one-time initialization cost is negligible compared to the massive 5x - 550x performance gains in actual Buffer operations.

[!TIP] atob/btoa Optimization: In modern React Native environments (Hermes), global.atob and global.btoa are natively implemented and highly optimized. react-native-nitro-buffer automatically detects and uses these native implementations if available, ensuring your app runs at peak performance while maintaining Node.js utility compatibility.

📦 Installation

npm install react-native-nitro-buffer
# or
yarn add react-native-nitro-buffer

iOS Setup

cd ios && pod install

📖 Usage

Import Buffer directly from the package. It follows the standard Node.js Buffer API.

import { Buffer } from 'react-native-nitro-buffer';

// 1. Allocation
const buf = Buffer.alloc(10);
buf.fill(0);

// 2. From String
const hello = Buffer.from('Hello World');
console.log(hello.toString('hex')); // 48656c6c6f20576f726c64

// 3. String Encoding/Decoding
const base64 = hello.toString('base64');
console.log(base64); // SGVsbG8gV29ybGQ=

const decoded = Buffer.from(base64, 'base64');
console.log(decoded.toString()); // Hello World

// 4. Binary Manipulation
const buf2 = Buffer.allocUnsafe(4);
buf2.writeUInt8(0x12, 0); // (Note: typed array methods available via standard Uint8Array API)

🧩 API Support

This library achieves 100% API compatibility with Node.js Buffer.

Static Methods

• Buffer.alloc(size, fill, encoding)
• Buffer.allocUnsafe(size)
• Buffer.from(array|string|buffer)
• Buffer.byteLength(string, encoding)
• Buffer.isBuffer(obj)
• Buffer.compare(buf1, buf2)
• Buffer.concat(list, totalLength)
• Buffer.isEncoding(encoding)
• Buffer.poolSize

Instance Methods

• Binary Read/Write:
  • readInt8, readUInt8, writeInt8, writeUInt8
  • readInt16LE/BE, readUInt16LE/BE, writeInt16LE/BE, writeUInt16LE/BE
  • readInt32LE/BE, readUInt32LE/BE, writeInt32LE/BE, writeUInt32LE/BE
  • readBigInt64LE/BE, readBigUInt64LE/BE, writeBigInt64LE/BE, writeBigUInt64LE/BE
  • readFloatLE/BE, readDoubleLE/BE, writeFloatLE/BE, writeDoubleLE/BE
  • readIntLE/BE, readUIntLE/BE, writeIntLE/BE, writeUIntLE/BE
• String/Search:
  • includes(value, byteOffset, encoding)
  • indexOf(value, byteOffset, encoding)
  • lastIndexOf(value, byteOffset, encoding)
  • fill(value, offset, end, encoding)
• Manipulation/Utils:
  • write(string, offset, length, encoding)
  • toString(encoding, start, end)
  • compare(target, ...)
  • copy(target, ...)
  • slice(start, end) (Returns a view, similar to Node.js subarray)
  • swap16(), swap32(), swap64()
  • toJSON()

🔄 Interoperability

react-native-nitro-buffer is designed to be fully interoperable with React Native's ecosystem.

• Standard Uint8Array: Instances are standard Uint8Arrays, so they work with any API accepting standard typed arrays.
• @craftzdog/react-native-buffer: Fully compatible. You can convert between the two or mix them in standard operations (like concat or compare) because both adhere to standard byte structures.

  import { Buffer as NitroBuffer } from 'react-native-nitro-buffer';
  import { Buffer as CraftzBuffer } from '@craftzdog/react-native-buffer';
  
  const nBuf = NitroBuffer.from('Hello');
  const cBuf = CraftzBuffer.from(nBuf); // Works!

⚠️ Compatibility Notes

toString('ascii') Behavior

When decoding binary data with non-ASCII bytes (0x80-0xFF), react-native-nitro-buffer follows the Node.js standard by replacing invalid bytes with the Unicode replacement character (U+FFFD, displayed as �).

const buf = Buffer.from([0x48, 0x69, 0x80, 0xFF, 0x21]); // "Hi" + invalid bytes + "!"
buf.toString('ascii');
// Nitro (Node.js compatible): "Hi��!" (length: 5)
// @craftzdog/react-native-buffer: "Hi!" (length: 5) - incorrectly drops invalid bytes

This ensures consistent behavior with Node.js when handling binary protocols like WebSocket messages containing mixed text and binary data (e.g., Microsoft TTS audio streams).

📄 License

ISC