react-native-nitro-buffer 0.0.2 → 0.0.4

package/README.md

@@ -14,23 +14,43 @@ A high-performance, Node.js compatible `Buffer` implementation for React Native,
 
 `react-native-nitro-buffer` is significantly faster than other Buffer implementations for React Native.
 
-**Benchmark Results (1MB Buffer operations):**
+### Device: iPad Air 5 (M1) - Physical Device
 
 | Operation | Nitro Buffer | Competitor (Craftz) | Improvement |
 |:---|:---:|:---:|:---:|
-| `fill(0)` | **0.019ms** | 10.36ms | **~545x 🚀** |
-| `write(utf8)` | **2.53ms** | 212.42ms | **~84x 🚀** |
-| `toString(utf8)` | **0.25ms** | 170.72ms | **~691x 🚀** |
-| `toString(base64)` | **0.68ms** | 3.37ms | **~5x 🚀** |
-| `from(base64)` | **1.37ms** | 146.70ms | **~107x 🚀** |
-| `toString(hex)` | **4.86ms** | 56.77ms | **~11.7x 🚀** |
-| `from(hex)` | **11.05ms** | 136.64ms | **~12.4x 🚀** |
-| `alloc(1MB)` | 0.39ms | 0.09ms | 0.23x |
+| `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)
 
-*> Benchmarks ran on iPad Air 5 (M1), averaging 50 iterations.*
+| 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 **10x - 700x** performance gains in actual Buffer operations.
+> **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
 
@@ -124,6 +144,21 @@ This library achieves **100% API compatibility** with Node.js `Buffer`.
     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 `�`).
+
+```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

package/cpp/HybridNitroBuffer.cpp

@@ -217,6 +217,206 @@ double HybridNitroBuffer::write(const std::shared_ptr<ArrayBuffer> &buffer,
   return actualWrite;
 }
 
+// UTF-8 replacement character (U+FFFD) encoded as UTF-8
+static const char UTF8_REPLACEMENT[] = "\xEF\xBF\xBD";
+
+// Fast validation: returns true if all data is valid UTF-8, false otherwise
+// This allows us to use memcpy for the common case of valid UTF-8
+static bool isValidUtf8(const uint8_t *data, size_t len) {
+  size_t i = 0;
+  while (i < len) {
+    uint8_t byte1 = data[i];
+
+    // ASCII (0x00-0x7F) - most common case
+    if (byte1 <= 0x7F) {
+      i++;
+      continue;
+    }
+
+    // Invalid leading byte
+    if (byte1 < 0xC2 || byte1 > 0xF4) {
+      return false;
+    }
+
+    // 2-byte sequence (0xC2-0xDF)
+    if (byte1 <= 0xDF) {
+      if (i + 1 >= len || (data[i + 1] & 0xC0) != 0x80) {
+        return false;
+      }
+      i += 2;
+      continue;
+    }
+
+    // 3-byte sequence (0xE0-0xEF)
+    if (byte1 <= 0xEF) {
+      if (i + 2 >= len)
+        return false;
+      uint8_t byte2 = data[i + 1];
+      uint8_t byte3 = data[i + 2];
+      if ((byte2 & 0xC0) != 0x80 || (byte3 & 0xC0) != 0x80)
+        return false;
+      // Check overlong and surrogate
+      if (byte1 == 0xE0 && byte2 < 0xA0)
+        return false;
+      if (byte1 == 0xED && byte2 >= 0xA0)
+        return false;
+      i += 3;
+      continue;
+    }
+
+    // 4-byte sequence (0xF0-0xF4)
+    if (i + 3 >= len)
+      return false;
+    uint8_t byte2 = data[i + 1];
+    uint8_t byte3 = data[i + 2];
+    uint8_t byte4 = data[i + 3];
+    if ((byte2 & 0xC0) != 0x80 || (byte3 & 0xC0) != 0x80 ||
+        (byte4 & 0xC0) != 0x80)
+      return false;
+    if (byte1 == 0xF0 && byte2 < 0x90)
+      return false;
+    if (byte1 == 0xF4 && byte2 > 0x8F)
+      return false;
+    i += 4;
+  }
+  return true;
+}
+
+// Slow path: Decode UTF-8 with replacement for invalid bytes
+// Only called when isValidUtf8 returns false
+static std::string decodeUtf8WithReplacementSlow(const uint8_t *data,
+                                                 size_t len) {
+  std::string result;
+  result.reserve(len + len / 10); // Add 10% for potential replacements
+
+  size_t i = 0;
+  while (i < len) {
+    uint8_t byte1 = data[i];
+
+    // ASCII (0x00-0x7F)
+    if (byte1 <= 0x7F) {
+      result.push_back(static_cast<char>(byte1));
+      i++;
+      continue;
+    }
+
+    // Invalid leading byte (0x80-0xBF or 0xF8-0xFF)
+    if (byte1 < 0xC2 || byte1 > 0xF4) {
+      result.append(UTF8_REPLACEMENT);
+      i++;
+      continue;
+    }
+
+    // 2-byte sequence (0xC2-0xDF)
+    if (byte1 <= 0xDF) {
+      if (i + 1 >= len || (data[i + 1] & 0xC0) != 0x80) {
+        result.append(UTF8_REPLACEMENT);
+        i++;
+        continue;
+      }
+      result.push_back(static_cast<char>(byte1));
+      result.push_back(static_cast<char>(data[i + 1]));
+      i += 2;
+      continue;
+    }
+
+    // 3-byte sequence (0xE0-0xEF)
+    if (byte1 <= 0xEF) {
+      if (i + 2 >= len) {
+        result.append(UTF8_REPLACEMENT);
+        i++;
+        continue;
+      }
+      uint8_t byte2 = data[i + 1];
+      uint8_t byte3 = data[i + 2];
+      if ((byte2 & 0xC0) != 0x80 || (byte3 & 0xC0) != 0x80 ||
+          (byte1 == 0xE0 && byte2 < 0xA0) || (byte1 == 0xED && byte2 >= 0xA0)) {
+        result.append(UTF8_REPLACEMENT);
+        i++;
+        continue;
+      }
+      result.push_back(static_cast<char>(byte1));
+      result.push_back(static_cast<char>(byte2));
+      result.push_back(static_cast<char>(byte3));
+      i += 3;
+      continue;
+    }
+
+    // 4-byte sequence (0xF0-0xF4)
+    if (i + 3 >= len) {
+      result.append(UTF8_REPLACEMENT);
+      i++;
+      continue;
+    }
+    uint8_t byte2 = data[i + 1];
+    uint8_t byte3 = data[i + 2];
+    uint8_t byte4 = data[i + 3];
+    if ((byte2 & 0xC0) != 0x80 || (byte3 & 0xC0) != 0x80 ||
+        (byte4 & 0xC0) != 0x80 || (byte1 == 0xF0 && byte2 < 0x90) ||
+        (byte1 == 0xF4 && byte2 > 0x8F)) {
+      result.append(UTF8_REPLACEMENT);
+      i++;
+      continue;
+    }
+    result.push_back(static_cast<char>(byte1));
+    result.push_back(static_cast<char>(byte2));
+    result.push_back(static_cast<char>(byte3));
+    result.push_back(static_cast<char>(byte4));
+    i += 4;
+  }
+
+  return result;
+}
+
+// Decode UTF-8 with WHATWG-compliant error handling
+// Uses fast path (memcpy) for valid UTF-8, slow path with replacement for
+// invalid
+static std::string decodeUtf8WithReplacement(const uint8_t *data, size_t len) {
+  // Fast path: if data is valid UTF-8, just copy it directly
+  if (isValidUtf8(data, len)) {
+    return std::string(reinterpret_cast<const char *>(data), len);
+  }
+  // Slow path: need to replace invalid sequences
+  return decodeUtf8WithReplacementSlow(data, len);
+}
+
+// Decode as latin1/binary - each byte maps directly to Unicode code point
+// 0x00-0xFF
+static std::string decodeLatin1(const uint8_t *data, size_t len) {
+  std::string result;
+  result.reserve(len * 2); // Worst case: all bytes > 0x7F need 2 bytes in UTF-8
+
+  for (size_t i = 0; i < len; i++) {
+    uint8_t byte = data[i];
+    if (byte <= 0x7F) {
+      result.push_back(static_cast<char>(byte));
+    } else {
+      // Encode as 2-byte UTF-8 sequence
+      result.push_back(static_cast<char>(0xC0 | (byte >> 6)));
+      result.push_back(static_cast<char>(0x80 | (byte & 0x3F)));
+    }
+  }
+
+  return result;
+}
+
+// Decode as ASCII - bytes > 0x7F are replaced with U+FFFD
+static std::string decodeAscii(const uint8_t *data, size_t len) {
+  std::string result;
+  result.reserve(len);
+
+  for (size_t i = 0; i < len; i++) {
+    uint8_t byte = data[i];
+    if (byte <= 0x7F) {
+      result.push_back(static_cast<char>(byte));
+    } else {
+      result.append(UTF8_REPLACEMENT);
+    }
+  }
+
+  return result;
+}
+
 std::string
 HybridNitroBuffer::decode(const std::shared_ptr<ArrayBuffer> &buffer,
                           double offset, double length,
@@ -232,8 +432,15 @@ HybridNitroBuffer::decode(const std::shared_ptr<ArrayBuffer> &buffer,
   size_t actualRead = std::min(available, count);
 
   if (encoding == "utf8" || encoding == "utf-8") {
-    // Check for null termination? No, ArrayBuffer may not be null terminated.
-    return std::string((char *)(data + start), actualRead);
+    // WHATWG-compliant UTF-8 decoding with replacement character for invalid
+    // sequences
+    return decodeUtf8WithReplacement(data + start, actualRead);
+  } else if (encoding == "latin1" || encoding == "binary") {
+    // Each byte maps to Unicode code point 0x00-0xFF
+    return decodeLatin1(data + start, actualRead);
+  } else if (encoding == "ascii") {
+    // ASCII with replacement for non-ASCII bytes
+    return decodeAscii(data + start, actualRead);
   } else if (encoding == "hex") {
     std::string hex;
     hex.reserve(actualRead * 2);
@@ -248,7 +455,8 @@ HybridNitroBuffer::decode(const std::shared_ptr<ArrayBuffer> &buffer,
     return base64_encode(data + start, (unsigned int)actualRead);
   }
 
-  return std::string((char *)(data + start), actualRead);
+  // Default: UTF-8 with replacement
+  return decodeUtf8WithReplacement(data + start, actualRead);
 }
 
 double HybridNitroBuffer::compare(const std::shared_ptr<ArrayBuffer> &a,

package/lib/utils.js

@@ -8,9 +8,15 @@ exports.transcode = transcode;
 exports.resolveObjectURL = resolveObjectURL;
 const Buffer_1 = require("./Buffer");
 function atob(data) {
+    if (typeof global.atob === 'function') {
+        return global.atob(data);
+    }
     return Buffer_1.Buffer.from(data, 'base64').toString('binary');
 }
 function btoa(data) {
+    if (typeof global.btoa === 'function') {
+        return global.btoa(data);
+    }
     return Buffer_1.Buffer.from(data, 'binary').toString('base64');
 }
 function isAscii(input) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-native-nitro-buffer",
-    "version": "0.0.2",
+    "version": "0.0.4",
     "description": "Node.js compatible buffer module for React Native",
     "main": "lib/index.js",
     "module": "lib/index.js",
@@ -30,7 +30,6 @@
         "@types/node": "^18.19.130",
         "@types/react": "*",
         "jest": "^29.0.0",
-        "react-native-nitro-modules": "*",
         "ts-jest": "^29.0.0",
         "typescript": "^5.0.0"
     },

package/src/utils.ts

@@ -2,10 +2,16 @@
 import { Buffer } from './Buffer'
 
 export function atob(data: string): string {
+    if (typeof global.atob === 'function') {
+        return global.atob(data)
+    }
     return Buffer.from(data, 'base64').toString('binary')
 }
 
 export function btoa(data: string): string {
+    if (typeof global.btoa === 'function') {
+        return global.btoa(data)
+    }
     return Buffer.from(data, 'binary').toString('base64')
 }