react-native-columnar

Zero-copy columnar ArrayBuffer transport from JSI C++ to JavaScript.

JSI modules often return datasets as arrays of objects — every row becomes a JS object, every value gets boxed, GC pressure grows. react-native-columnar packs all values into one binary buffer and exposes each column as a typed array view over the same memory. No objects, no parsing, no copy.

---

⚡ Benchmark

10 000 iterations · 5 columns · iPhone 16 Pro

id (int32) | status (uint8) | isActive (uint8) | createdAt (double) | updatedAt (double)

Rows	Array of objects	react-native-columnar	Speedup
100	~418.81 ms	~14.96 ms	27×
500	~2079.81 ms	~22.06 ms	94×
1000	~4360.11 ms	~35.89 ms	121×
2000	~9444.47 ms	~45.39 ms	208×

---

🎯 Best use cases

SQLite result sets · Frame processor outputs · Sensor streams · Analytics events · Realtime charts · Large JSI payloads

---

📦 Installation

npm install react-native-columnar
# or
yarn add react-native-columnar

iOS — headers are picked up automatically via CocoaPods.

Android — app project

Autolinking registers the package automatically. Add to android/app/build.gradle:

android {
  buildFeatures { prefab true }
}

Then in CMakeLists.txt:

find_package(react-native-columnar REQUIRED CONFIG)
target_link_libraries(${YOUR_LIBRARY_NAME} react-native-columnar::react-native-columnar)

Android — standalone library

Add to package.json:

{ "dependencies": { "react-native-columnar": "*" } }

Then in CMakeLists.txt (NODE_MODULES_DIR is already passed by any JSI library):

include_directories(${NODE_MODULES_DIR}/react-native-columnar/cpp)

In your C++ files:

#include "react-native-columnar.h"

---

🔧 C++ side

1. Define a schema

#include "react-native-columnar.h"

#define USER_COLUMNS(X)       \
  X(int32_t, id)              \
  X(uint8_t, status)          \
  X(uint8_t, isActive)        \
  X(double,  createdAt)       \
  X(double,  updatedAt)

DECLARE_BINARY_SCHEMA(UserSchema, USER_COLUMNS)

Generates UserSchema with columnCount, byteSize(), and a Columns struct of std::span views.

2. Write and return an ArrayBuffer

using namespace rn_columnar;

jsi::Value getUsers(jsi::Runtime& rt, const jsi::Value*, const jsi::Value* args, size_t) {
  const uint32_t rows = static_cast<uint32_t>(args[0].asNumber());

  ColumnarWriterBuilder<UserSchema> builder(rows);
  auto cols = UserSchema::createColumns(builder);

  for (uint32_t i = 0; i < rows; ++i) {
    cols.id[i]        = dbRow[i].id;
    cols.status[i]    = dbRow[i].status;
    cols.isActive[i]  = dbRow[i].isActive;
    cols.createdAt[i] = dbRow[i].createdAt;
    cols.updatedAt[i] = dbRow[i].updatedAt;
  }

  return builder.toArrayBuffer(rt); // zero-copy move into JSI
}

---

🟦 JS side

1. Define the schema

Must match column order and types from C++:

import { createBufferReader, ColumnType } from 'react-native-columnar';

const USER_SCHEMA = [
  ColumnType.Int32,    // id
  ColumnType.Uint8,    // status
  ColumnType.Uint8,    // isActive
  ColumnType.Float64,  // createdAt
  ColumnType.Float64,  // updatedAt
] as const;

2. Read the buffer

const buffer: ArrayBuffer = __getUsers();

const [header, columns] = createBufferReader(buffer, USER_SCHEMA);
const [idCol, statusCol, isActiveCol, createdAtCol, updatedAtCol] = columns;
// idCol — Int32Array  |  statusCol — Uint8Array  |  createdAtCol — Float64Array

const id        = idCol[0];
const status    = statusCol[0];
const isActive  = isActiveCol[0];
const createdAt = createdAtCol[0];
const updatedAt = updatedAtCol[0];

All columns are zero-copy typed array views — the buffer is never copied.

API

createBufferReader(buffer: ArrayBuffer, schema: readonly ColumnType[])
  // → [header: Int32Array, columns: TypedArray[]]
  // header[0] = row count, header[1] = column count

ColumnType mapping

ColumnType	C++ type	JS view	Bytes	Tip
Int8	int8_t	Int8Array	1
Uint8	uint8_t	Uint8Array	1	bool, flags
Int16	int16_t	Int16Array	2
Uint16	uint16_t	Uint16Array	2
Int32	int32_t	Int32Array	4	id, count, enum
Uint32	uint32_t	Uint32Array	4
Float32	float	Float32Array	4	screen coords (~7 sig. digits)
Float64	double	Float64Array	8	timestamp, price

---

⚠️ Limitations

Designed for dense numeric data only. Strings, nullable values, nested objects, and variable-length fields are not supported natively — encode them as fixed-width columns using ids, offsets, or sentinel values.

---

🛠 Troubleshooting

react-native-columnar.h not found on Android — check that prefab true is enabled and CMake links the package correctly.

std::span errors — set C++20 on the target that includes the header.

RangeError in JS — JS and C++ schemas are out of sync. Check column order and types match exactly (int32_t → Int32, double → Float64).

Values look shifted — one wrong type shifts all following columns. Compare schemas line by line.

---

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT