RFC: Add batch read/write APIs to reduce JS<->C++ overhead

[IberAI]

Hi thank you this library is already blazingly fast. Im not an expert but Im wondering if adding a simple way to batch multiple reads/writes into a single native operation could further improve performance?

Idea: collapse N JS <-> native calls into 1 do the work natively and coalesce change events

I was thinking it would look something like this when you use it

// Write a bunch of values at once
storage.setMany([
  ['loggedIn', true],
  ['user:id', 1234],
  ['user:name', 'Ada'],
])

// Read multiple keys with one call
const { ['user:id']: id, ['user:name']: name } = storage.getMany(['user:id', 'user:name'])

// Delete multiple keys efficiently
storage.deleteMany(['tmp:1', 'tmp:2', 'tmp:3'])

// Coalesce event emissions & native calls
storage.batch(() => {
  storage.setMany([
    ['features:welcome', true],
    ['features:newHome', false],
  ])
  storage.deleteMany(['legacy:flag'])
})

[maintenance-hans]

Guten Tag, Hans here! 🍻 Vielen Dank for your suggestion! Your idea to add batch read/write APIs sounds interesting and could indeed improve performance by reducing JS to C++ overhead. Can you please provide any benchmarks or performance metrics that illustrate the current performance and potential gains? That would help mrousavy evaluate your proposal better. Keep up ze good work!

Note: If you think I made a mistake, please ping @mrousavy to take a look.

[IberAI]

Hi, i tried implementing and benchmarking my batching idea as best of my ability with the resources i have. I hope it would be helpful for this repo.

What I changed & what I measured. I added a setMany JSI method that accepts either [[k,v], …] or a flat [k1,v1,k2,v2,…] array and loops natively, so bursty writes pay one JS -> native hop instead of N. On an Android release build on real hardware with N = 100,000 and Runs = 100, I saw: set(ms) per-key 127, batched (pairs) 93, batched (flat) 262; del(ms) per-key 88, batched 32. In other words, batching with the pair array improved writes by ~27% (≈1.37×) and deletes by ~64% (≈2.75×). The flat path looked slower here because the benchmark (by design) includes the JS cost of building the flat array inside the timed section; prebuilding that array before the timer (or exposing typed batchers like setManyStrings) removes that overhead and should reveal the native fast-path win.

How the benchmark works (briefly). For each run it builds N entries, then times five blocks with t0 = now(); …; elapsed = now() - t0: (1) per-key set in a loop, (2) setMany([[k,v],…]) once, (3) setMany([k1,v1,…]) once, (4) per-key delete in a loop, and (5) deleteMany([...]) once (after repopulating). Each “set” variant starts from an empty store (clearAll) so they’re comparable; delete batching repopulates just before timing. Results are averaged over Runs to smooth noise, and the benchmark uses a dedicated MMKV instance (no listeners) so UI work doesn’t affect the numbers.

Platform	Build	Device	N (items)	Runs
Android	Release	Real device	100,000	100

Operation	Variant	Time (ms)	Speedup vs per-key	Notes
set	per-key	127	1.00×	baseline
set	batched (pairs [[k,v],…])	93	1.37×	1 JS -> native + native loop
set	batched (flat [k1,v1,…])	262	0.48× (slower)	includes JS flattening cost
delete	per-key	88	1.00×	baseline
delete	batched (deleteMany)	32	2.75×	1 JS -> native + native loop

Code

MmkvHostObject.cpp

  // ===================== NEW: setMany =====================
  if (propName == "setMany") {
    // MMKV.setMany(entries)
    // Accepts either:
    //   1) flat array:   [k1, v1, k2, v2, ...]             
    //   2) pair array:   [[k1, v1], [k2, v2], ...]          
    return jsi::Function::createFromHostFunction(
        runtime, jsi::PropNameID::forAscii(runtime, propName),
        1, // entries
        [this](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args,
               size_t count) -> jsi::Value {
          if (count != 1 || !args[0].isObject() || !args[0].getObject(rt).isArray(rt))
              [[unlikely]] {
            throw jsi::JSError(rt, "MMKV::setMany: First argument ('entries') must be an array.");
          }

          jsi::Array arr = args[0].getObject(rt).getArray(rt);
          const size_t len = arr.length(rt);
          if (len == 0) {
            return jsi::Value::undefined();
          }

          // -------- FAST PATH: flat [k, v, k, v, ...] --------
          // Heuristic: first element not an Array => assume flat form.
          const bool looksFlat = !arr.getValueAtIndex(rt, 0).isObject();

          if (looksFlat) {
            // Iterate in steps of 2; skip incomplete/invalid pairs safely.
            for (size_t i = 0; i + 1 < len; i += 2) {
              jsi::Value kVal = arr.getValueAtIndex(rt, i);
              if (!kVal.isString())
                continue; // skip invalid key

              std::string key = kVal.getString(rt).utf8(rt);
              const jsi::Value v = arr.getValueAtIndex(rt, i + 1);

              bool ok = false;
              if (v.isBool()) {
                ok = instance->set(v.getBool(), key);
              } else if (v.isNumber()) {
                ok = instance->set(v.getNumber(), key);
              } else if (v.isString()) {
                std::string s = v.getString(rt).utf8(rt);
                ok = instance->set(s, key);
              } else if (v.isObject() && v.getObject(rt).isArrayBuffer(rt)) {
                jsi::ArrayBuffer ab = v.getObject(rt).getArrayBuffer(rt);
                MMBuffer data(ab.data(rt), ab.size(rt), MMBufferNoCopy);
                ok = instance->set(data, key);
              } else {
                // Unsupported type: treat as no-op to mirror single 'set' behavior
                ok = true;
              }

              if (!ok) [[unlikely]] {
                if (instance->isReadOnly()) {
                  throw jsi::JSError(rt, "Failed to set " + key +
                                             " (batch, flat)! This instance is read-only!");
                } else {
                  throw jsi::JSError(rt, "Failed to set " + key + " (batch, flat)!");
                }
              }
            }

            return jsi::Value::undefined();
          }

          // -------- COMPAT PATH: [[key, value], ...] --------
          for (size_t i = 0; i < len; ++i) {
            jsi::Value pairVal = arr.getValueAtIndex(rt, i);
            if (!pairVal.isObject() || !pairVal.getObject(rt).isArray(rt))
              continue;

            jsi::Array pair = pairVal.getObject(rt).getArray(rt);
            if (pair.length(rt) < 2)
              continue;

            jsi::Value kVal = pair.getValueAtIndex(rt, 0);
            if (!kVal.isString())
              continue;

            std::string key = kVal.getString(rt).utf8(rt);
            const jsi::Value v = pair.getValueAtIndex(rt, 1);

            bool ok = false;
            if (v.isBool()) {
              ok = instance->set(v.getBool(), key);
            } else if (v.isNumber()) {
              ok = instance->set(v.getNumber(), key);
            } else if (v.isString()) {
              std::string s = v.getString(rt).utf8(rt);
              ok = instance->set(s, key);
            } else if (v.isObject() && v.getObject(rt).isArrayBuffer(rt)) {
              jsi::ArrayBuffer ab = v.getObject(rt).getArrayBuffer(rt);
              MMBuffer data(ab.data(rt), ab.size(rt), MMBufferNoCopy);
              ok = instance->set(data, key);
            } else {
              ok = true; // ignore unsupported types
            }

            if (!ok) [[unlikely]] {
              if (instance->isReadOnly()) {
                throw jsi::JSError(rt, "Failed to set " + key +
                                           " (batch)! This instance is read-only!");
              } else {
                throw jsi::JSError(rt, "Failed to set " + key + " (batch)!");
              }
            }
          }

          return jsi::Value::undefined();
        });
  }
  // =================== END NEW: setMany ===================

App.tsx in example project

import * as React from 'react';
import {
  Alert,
  Button,
  Platform,
  StyleSheet,
  Text,
  TextInput,
  View,
  useColorScheme,
} from 'react-native';
import { MMKV, useMMKVListener, useMMKVString } from 'react-native-mmkv';

/** Default app storage (has listener, shown in UI) */
const storage = new MMKV();
/** Separate instance for benchmarks (no listeners -> cleaner signal) */
const bench = new MMKV({ id: 'bench' as any });

/** Helpers to detect native batching and call safely */
const hasBatched = (target: any) =>
  typeof target?.setMany === 'function' && typeof target?.deleteMany === 'function';

const batchSetPairs = (target: MMKV, entries: Array<[string, string]>) => {
  const anyTarget = target as any;
  if (typeof anyTarget.setMany === 'function') {
    anyTarget.setMany(entries); // [[k,v],[k,v],...]
  } else {
    for (const [k, v] of entries) target.set(k, v);
  }
};

const batchSetFlat = (target: MMKV, entries: Array<[string, string]>) => {
  const flat: any[] = [];
  for (const [k, v] of entries) flat.push(k, v);
  const anyTarget = target as any;
  if (typeof anyTarget.setMany === 'function') {
    anyTarget.setMany(flat); // [k1,v1,k2,v2,...] -> fast path in native
  } else {
    for (let i = 0; i + 1 < flat.length; i += 2) {
      target.set(flat[i] as string, flat[i + 1] as string);
    }
  }
};

const batchDelete = (target: MMKV, keys: string[]) => {
  const anyTarget = target as any;
  if (typeof anyTarget.deleteMany === 'function') {
    anyTarget.deleteMany(keys);
  } else {
    for (const k of keys) target.delete(k);
  }
};

export default function App() {
  // Simple KV UI state
  const [key, setKey] = React.useState('');
  const [text, setText] = React.useState('');
  const [keys, setKeys] = React.useState<string[]>([]);

  // Benchmark config/state
  const [N, setN] = React.useState('2000');
  const [runs, setRuns] = React.useState('3');
  const [benchResult, setBenchResult] = React.useState('—');

  const colorScheme = useColorScheme();
  const isDark = colorScheme === 'dark';
  const stylesDyn = createDynamicStyles(isDark);

  // Example hook demo (unchanged)
  const [example, setExample] = useMMKVString('yeeeet');
  React.useEffect(() => {
    const id = setInterval(() => {
      setExample((v) => (v === 'yeeeet' ? undefined : 'yeeeet'));
    }, 1000);
    return () => clearInterval(id);
  }, [setExample, example]);

  // Keep visible key list in sync with default storage
  useMMKVListener((k) => {
    console.log(`${k} changed! New size: ${storage.size}`);
    try {
      setKeys(storage.getAllKeys());
    } catch { }
  });
  const refreshKeys = React.useCallback(() => {
    try {
      setKeys(storage.getAllKeys());
    } catch (e) {
      console.error('getAllKeys failed:', e);
    }
  }, []);
  React.useEffect(() => {
    refreshKeys();
  }, [refreshKeys]);

  const save = React.useCallback(() => {
    if (!key) {
      Alert.alert('Empty key!', 'Enter a key first.');
      return;
    }
    try {
      storage.set(key, text);
      refreshKeys();
    } catch (e) {
      console.error(e);
      Alert.alert('Failed to set value!', JSON.stringify(e));
    }
  }, [key, text, refreshKeys]);

  const read = React.useCallback(() => {
    if (!key) {
      Alert.alert('Empty key!', 'Enter a key first.');
      return;
    }
    try {
      const value = storage.getString(key);
      Alert.alert('Result', `"${key}" = "${value}"`);
    } catch (e) {
      console.error(e);
      Alert.alert('Failed to get value!', JSON.stringify(e));
    }
  }, [key]);

  const batchDemo = React.useCallback(() => {
    try {
      const entries = Array.from({ length: 10 }, (_, i) => [`demo:${i}`, `v${i}`] as [string, string]);
      batchSetPairs(storage, entries);
      refreshKeys();
      Alert.alert('Batch demo', 'Wrote 10 keys with one call.');
    } catch (e) {
      console.error(e);
      Alert.alert('Batch demo failed', JSON.stringify(e));
    }
  }, [refreshKeys]);

  /** Small util: stable clock */
  const now = React.useCallback(() => (global as any)?.performance?.now?.() ?? Date.now(), []);

  /** Run micro-bench: per-key vs pairs vs flat, with configurable N & runs */
  const runningRef = React.useRef(false);
  const runBenchmark = React.useCallback(async () => {
    if (runningRef.current) return;
    runningRef.current = true;
    setBenchResult('Running…');

    const total = Math.max(1, Math.min(10, Number(runs) || 1)); // cap runs 1..10 for sanity
    const count = Math.max(100, Math.min(100_000, Number(N) || 1000)); // cap N

    const oneRun = () => {
      const entries = Array.from({ length: count }, (_, i) => [`bench:${i}`, `v${i}`] as [string, string]);
      const keyList = entries.map(([k]) => k);

      // Warmup
      (bench as any).clearAll?.();

      // per-key set
      let t = now();
      for (const [k, v] of entries) bench.set(k, v);
      const perKeySet = Math.round(now() - t);

      // batched set (pairs)
      (bench as any).clearAll?.();
      t = now();
      batchSetPairs(bench, entries);
      const batchedSetPairs = Math.round(now() - t);

      // batched set (flat)
      (bench as any).clearAll?.();
      t = now();
      batchSetFlat(bench, entries);
      const batchedSetFlat = Math.round(now() - t);

      // per-key delete
      t = now();
      for (const k of keyList) bench.delete(k);
      const perKeyDel = Math.round(now() - t);

      // batched delete
      batchSetFlat(bench, entries); // repopulate quickly
      t = now();
      batchDelete(bench, keyList);
      const batchedDel = Math.round(now() - t);

      return { perKeySet, batchedSetPairs, batchedSetFlat, perKeyDel, batchedDel };
    };

    const results = [];
    for (let r = 0; r < total; r++) {
      results.push(oneRun());
      // tiny delay to yield UI thread if needed
      await new Promise((res) => setTimeout(res, 10));
    }

    const sum = results.reduce(
      (acc, x) => ({
        perKeySet: acc.perKeySet + x.perKeySet,
        batchedSetPairs: acc.batchedSetPairs + x.batchedSetPairs,
        batchedSetFlat: acc.batchedSetFlat + x.batchedSetFlat,
        perKeyDel: acc.perKeyDel + x.perKeyDel,
        batchedDel: acc.batchedDel + x.batchedDel,
      }),
      { perKeySet: 0, batchedSetPairs: 0, batchedSetFlat: 0, perKeyDel: 0, batchedDel: 0 }
    );
    const avg = Object.fromEntries(
      Object.entries(sum).map(([k, v]) => [k, Math.round((v as number) / total)])
    ) as Record<string, number>;

    const nativeBatched = hasBatched(bench);
    const env =
      `${Platform.OS} | ${__DEV__ ? 'Debug' : 'Release'} | ` +
      `JSI:${(global as any)?.HermesInternal ? 'Hermes' : 'JSC/Other'} | ` +
      `batched:${nativeBatched ? 'native' : 'fallback'}`;

    const msg =
      `${env}\n` +
      `N=${count}, runs=${total}\n` +
      `set(ms): per-key ${avg.perKeySet}  | pairs ${avg.batchedSetPairs}  | flat ${avg.batchedSetFlat}\n` +
      `del(ms): per-key ${avg.perKeyDel}  | batched ${avg.batchedDel}`;

    console.log('[MMKV bench]\n' + msg);
    setBenchResult(msg);
    runningRef.current = false;
  }, [N, runs, now]);

  const clearBench = React.useCallback(() => {
    try {
      (bench as any).clearAll?.();
      Alert.alert('Bench store cleared', 'The "bench" instance is empty now.');
    } catch (e) {
      console.error(e);
    }
  }, []);

  return (
    <View style={[styles.container, stylesDyn.container]}>
      <Text style={[styles.h1, stylesDyn.title]}>MMKV playground</Text>

      {/* KV section */}
      <Text style={[styles.sub, stylesDyn.keys]}>
        Keys: {keys.length ? keys.join(', ') : '(none)'}
      </Text>

      <View style={styles.row}>
        <Text style={[styles.label, stylesDyn.title]}>Key</Text>
        <TextInput
          placeholder="Key"
          placeholderTextColor={isDark ? '#999' : '#666'}
          style={[styles.input, stylesDyn.input]}
          autoCapitalize="none"
          value={key}
          onChangeText={setKey}
        />
      </View>

      <View style={styles.row}>
        <Text style={[styles.label, stylesDyn.title]}>Value</Text>
        <TextInput
          placeholder="Value"
          placeholderTextColor={isDark ? '#999' : '#666'}
          style={[styles.input, stylesDyn.input]}
          autoCapitalize="none"
          value={text}
          onChangeText={setText}
        />
      </View>

      <View style={styles.rowButtons}>
        <Button title="Save" onPress={save} />
        <View style={styles.spacer} />
        <Button title="Read" onPress={read} />
        <View style={styles.spacer} />
        <Button title="Batch demo (10)" onPress={batchDemo} />
      </View>

      {/* Bench controls */}
      <View style={styles.divider} />
      <Text style={[styles.h2, stylesDyn.title]}>Benchmark</Text>

      <View style={styles.row}>
        <Text style={[styles.label, stylesDyn.title]}>N</Text>
        <TextInput
          placeholder="Count (e.g. 2000)"
          placeholderTextColor={isDark ? '#999' : '#666'}
          style={[styles.input, stylesDyn.input]}
          keyboardType="numeric"
          value={N}
          onChangeText={setN}
        />
      </View>

      <View style={styles.row}>
        <Text style={[styles.label, stylesDyn.title]}>Runs</Text>
        <TextInput
          placeholder="Runs (e.g. 3)"
          placeholderTextColor={isDark ? '#999' : '#666'}
          style={[styles.input, stylesDyn.input]}
          keyboardType="numeric"
          value={runs}
          onChangeText={setRuns}
        />
      </View>

      <View style={styles.rowButtons}>
        <Button title="Run benchmark" onPress={runBenchmark} />
        <View style={styles.spacer} />
        <Button title="Clear bench store" onPress={clearBench} />
      </View>

      <Text style={[styles.mono, stylesDyn.keys]} selectable>
        {benchResult}
      </Text>

      <Text style={[styles.tip, stylesDyn.keys]}>
        Tip: For real numbers, test a **Release** build. Debug/Metro can distort micro-benchmarks.
      </Text>
    </View>
  );
}

/* ---------- styles ---------- */

const createDynamicStyles = (isDark: boolean) =>
  StyleSheet.create({
    container: { backgroundColor: isDark ? '#000' : '#fff' },
    title: { color: isDark ? '#fff' : '#000' },
    keys: { color: isDark ? '#bbb' : '#666' },
    input: {
      color: isDark ? '#fff' : '#000',
      borderColor: isDark ? '#555' : '#000',
      backgroundColor: isDark ? '#1f1f1f' : '#fff',
    },
  });

const styles = StyleSheet.create({
  container: {
    flex: 1,
    paddingTop: 42,
    paddingHorizontal: 18,
  },
  h1: {
    fontSize: 20,
    fontWeight: '700',
    marginBottom: 8,
  },
  h2: {
    fontSize: 16,
    fontWeight: '600',
    marginTop: 8,
    marginBottom: 4,
  },
  sub: {
    fontSize: 12,
    marginBottom: 12,
  },
  row: {
    flexDirection: 'row',
    alignItems: 'center',
  },
  rowButtons: {
    flexDirection: 'row',
    alignItems: 'center',
    marginTop: 8,
  },
  label: {
    width: 60,
    fontSize: 14,
    marginRight: 8,
  },
  input: {
    flex: 1,
    borderWidth: StyleSheet.hairlineWidth,
    borderRadius: 6,
    paddingHorizontal: 10,
    paddingVertical: 8,
    fontSize: 14,
    marginVertical: 8,
  },
  spacer: { width: 12 },
  divider: {
    height: 1,
    backgroundColor: '#4444',
    marginVertical: 12,
  },
  mono: {
    marginTop: 12,
    fontFamily: Platform.OS === 'ios' ? 'Menlo' : 'monospace',
    fontSize: 12,
  },
  tip: {
    fontSize: 12,
    marginTop: 8,
  },
});

[mrousavy]

I played around with this idea 2 years ago: #535

But I don't think this is worth it. The JS <> C++ overhead is minimal compared to actually writing to disk.

[mrousavy]

Sorry just saw your second comment - it's interesting that you see improvements, but I think those are pretty rare use-cases. I don't think apps use batching that often that it actually makes sense. Not sure

[IberAI]

The performance improvements might be device specific. I know its a rare use case. I was thinking it would be useful on a cold start.