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.

$3

| 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 |

$3

| 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

``bash
npm install react-native-nitro-buffer


or


yarn add react-native-nitro-buffer
`

$3

`bash
cd ios && pod install
`

📖 Usage

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

`typescript
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.

$3


* 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

$3

* 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.
`typescript
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

$3

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 �).

`javascript
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