Performance

GUN is designed for high-performance, real-time applications. The engine is capable of 20M+ API operations per second while maintaining a tiny footprint of just ~9KB gzipped. Source: ~/workspace/source/README.md:180

Performance Characteristics

Throughput

20M+ API ops/sec: In-memory operations on modern hardware
Sub-millisecond latency: For local reads and writes
Streaming writes: No blocking on disk I/O
Batched network I/O: Multiple messages sent together

Memory Efficiency

9KB core engine: Minimal browser footprint
Configurable memory limits: Control cache size
Automatic garbage collection: Least-recently-used eviction

const gun = Gun({
  memory: 1000000000, // ~1GB memory cache
  max: 300000000 * 0.3 // ~90MB max message size
});

Source: ~/workspace/source/src/mesh.js:15-16

Optimization Strategies

1. Minimize Subscriptions

Each .on() creates a live subscription. Limit subscriptions to only what you need:

// ❌ BAD: Too many subscriptions
gun.get('users').map().on(user => {
  console.log(user);
});

// ✅ GOOD: Use .once() for one-time reads
gun.get('users').map().once(user => {
  console.log(user);
});

// ✅ GOOD: Unsubscribe when done
const unsub = gun.get('data').on(data => {
  console.log(data);
});

// Later
unsub.off();

GUN warns when you have more than 10,000 active subscriptions: Source: ~/workspace/source/src/mesh.js:336

2. Batch Writes

Group multiple writes into a single operation:

// ❌ BAD: Multiple separate writes
gun.get('user').get('name').put('Alice');
gun.get('user').get('age').put(30);
gun.get('user').get('email').put('alice@example.com');

// ✅ GOOD: Single batched write
gun.get('user').put({
  name: 'Alice',
  age: 30,
  email: 'alice@example.com'
});

3. Use Property Paths

Access nested data efficiently:

// ❌ SLOWER: Multiple get() calls
gun.get('user').get('profile').get('avatar').get('url').once(...);

// ✅ FASTER: Direct path access (if supported by your GUN version)
gun.get('user').get('profile.avatar.url').once(...);

4. Limit Graph Depth

Deeply nested graphs are slower to traverse:

// ❌ BAD: Deep nesting
gun.get('a').get('b').get('c').get('d').get('e').get('f');

// ✅ GOOD: Flatter structure
gun.get('a-b-c').get('value');

5. Configure Message Batching

const gun = Gun({
  gap: 0,    // Milliseconds to wait before sending batch (default: 0)
  pack: 3000, // Target batch packet size (default: ~3KB)
  puff: 9    // Messages processed per event loop tick
});

Source: ~/workspace/source/src/mesh.js:14-17

gap: Lower values = faster sync, higher network overhead
pack: Larger values = more efficient network use, higher latency
puff: Higher values = faster processing, more CPU blocking

6. Enable Super Peer Mode

For relay peers, enable super mode to optimize routing:

const gun = Gun({
  super: true,  // Optimize for relay/server role
  faith: true   // Trust incoming data (performance optimization)
});

Source: ~/workspace/source/lib/server.js:8-9 Warning: Only enable faith: true on trusted relay peers, not in browsers.

Storage Performance

In-Memory Only

For maximum performance, run without persistence:

const gun = Gun(); // No storage plugin

File System Storage

Node.js file system storage:

const gun = Gun({
  file: 'data.json' // Uses gun/lib/rfs.js
});

RAD Storage

GUN’s optimized storage format:

const gun = Gun({
  rad: true // Radix storage for better performance
});

S3 Storage

Amazon S3 integration:

const gun = Gun({
  s3: {
    key: process.env.AWS_ACCESS_KEY_ID,
    secret: process.env.AWS_SECRET_ACCESS_KEY,
    bucket: process.env.AWS_S3_BUCKET
  }
});

Network Performance

WebSocket vs HTTP

WebSocket provides significant performance benefits:

Persistent connection: No TCP handshake overhead
Bidirectional: Real-time updates
Lower latency: No HTTP header overhead

// Automatically uses WebSocket when available
const gun = Gun({
  peers: ['http://localhost:8765/gun'] // Upgrades to ws://
});

Connection Pooling

Limit concurrent peer connections:

const gun = Gun({
  rtc: {
    max: 55 // Max WebRTC connections (default)
  }
});

Source: ~/workspace/source/lib/webrtc.js:36

Multicast for Local Networks

UDP multicast is extremely fast for local networks:

const gun = Gun({
  multicast: {
    address: '233.255.255.255',
    port: 8765
  }
});

Source: ~/workspace/source/lib/multicast.js:10-13

JSON Performance

Async JSON Parsing

GUN supports asynchronous JSON parsing to prevent UI blocking:

// Install: npm install gun/lib/yson.js
require('gun/lib/yson');

YSON (yielding JSON) parses large payloads without blocking the event loop. Source: ~/workspace/source/src/mesh.js:5-8

Warning System

GUN warns if JSON operations take too long:

// "Warning: JSON blocking CPU detected. Add gun/lib/yson.js to fix."

Source: ~/workspace/source/src/mesh.js:8

CPU Optimization

Event Loop Scheduling

GUN uses setTimeout.turn for cooperative multitasking:

// Process messages in chunks to avoid blocking
function processQueue(){
  const chunk = queue.splice(0, puff); // Process 'puff' items
  chunk.forEach(process);
  
  if(queue.length){
    setTimeout(processQueue, 0); // Yield to event loop
  }
}

Source: ~/workspace/source/src/mesh.js:18

Configurable Processing Rate

const gun = Gun({
  puff: 9 // Process 9 messages per tick (default)
});

// Higher puff = faster but more blocking
// Lower puff = slower but less blocking

Source: ~/workspace/source/src/mesh.js:17

Monitoring Performance

Enable Statistics

console.STAT = {};

setInterval(() => {
  console.log('Stats:', {
    peers: console.STAT.peers,
    memory: console.STAT.memused,
    messagesIn: gun.opt().mesh.hear.c,
    messagesOut: gun.opt().mesh.say.c,
    bytesIn: gun.opt().mesh.hear.d,
    bytesOut: gun.opt().mesh.say.d
  });
}, 1000);

Source: ~/workspace/source/src/mesh.js:103, 195, 328

Message Counters

const mesh = gun.opt().mesh;

console.log('Messages received:', mesh.hear.c);
console.log('Bytes received:', mesh.hear.d);
console.log('Messages sent:', mesh.say.c);
console.log('Bytes sent:', mesh.say.d);

Source: ~/workspace/source/src/mesh.js:103, 195

Latency Tracking

gun.on('out', function(msg){
  msg.DBG = {out: Date.now()};
  this.to.next(msg);
});

gun.on('in', function(msg){
  if(msg.DBG){
    const latency = Date.now() - msg.DBG.out;
    console.log('Round-trip latency:', latency, 'ms');
  }
  this.to.next(msg);
});

Profiling

Node.js Profiling

GUN includes built-in profiling support:

# Start with profiling enabled
node --prof server.js

# Generate flame graph
npm run debug

# Open v8data.json in https://mapbox.github.io/flamebearer/

Source: ~/workspace/source/package.json:12

Browser Profiling

Use browser DevTools:

Open Performance tab
Record while using your app
Look for GUN-related function calls
Identify bottlenecks

Benchmarking

Write Performance

const gun = Gun();
const iterations = 1000000;

const start = Date.now();

for(let i = 0; i < iterations; i++){
  gun.get('test').get(i).put({value: i});
}

const elapsed = Date.now() - start;
const opsPerSec = iterations / (elapsed / 1000);

console.log(`${opsPerSec.toFixed(0)} ops/sec`);

Read Performance

const gun = Gun();
const iterations = 1000000;

// Prepare data
for(let i = 0; i < 1000; i++){
  gun.get('test').get(i).put({value: i});
}

const start = Date.now();
let completed = 0;

for(let i = 0; i < iterations; i++){
  gun.get('test').get(i % 1000).once(() => {
    if(++completed === iterations){
      const elapsed = Date.now() - start;
      const opsPerSec = iterations / (elapsed / 1000);
      console.log(`${opsPerSec.toFixed(0)} ops/sec`);
    }
  });
}

Production Optimizations

1. Use a CDN

<!-- Serve GUN from CDN -->
<script src="https://cdn.jsdelivr.net/npm/gun/gun.min.js"></script>

2. Enable Compression

const express = require('express');
const compression = require('compression');
const Gun = require('gun');

const app = express();
app.use(compression()); // Gzip responses
app.use(Gun.serve);

3. Use Process Clustering

const cluster = require('cluster');
const numCPUs = require('os').cpus().length;

if(cluster.isMaster){
  for(let i = 0; i < numCPUs; i++){
    cluster.fork();
  }
  
  cluster.on('exit', () => {
    cluster.fork(); // Restart on crash
  });
} else {
  // Worker process
  const Gun = require('gun');
  const server = require('http').createServer();
  
  Gun({web: server.listen(8765)});
}

Source: ~/workspace/source/examples/http.js:2-5

4. Configure Timeouts

const gun = Gun({
  lack: 9000 // Time to wait before retrying failed peer (ms)
});

Source: ~/workspace/source/src/mesh.js:330

5. Limit Message Size

const gun = Gun({
  max: 300000000 * 0.3 // Max message size (~90MB)
});

Source: ~/workspace/source/src/mesh.js:15 Large messages are rejected: Source: ~/workspace/source/src/mesh.js:26

Common Performance Issues

Issue: High Memory Usage

Cause: Too many subscriptions or large datasets in memory Solution:

// Unsubscribe from unused data
const off = gun.get('data').on(callback);
off(); // Stop listening

// Use .once() instead of .on()
gun.get('data').once(callback);

// Configure memory limits
const gun = Gun({
  memory: 100000000 // 100MB limit
});

Issue: Slow Initial Load

Cause: Loading large datasets from storage Solution:

// Lazy load data
gun.get('users').map().once(user => {
  // Only load what you need
  if(user.active){
    displayUser(user);
  }
});

// Use pagination
gun.get('items').get('page1').map().once(...);

Issue: Network Congestion

Cause: Too many messages, large messages Solution:

// Batch updates
const updates = {};
Object.assign(updates, {prop1: val1, prop2: val2});
gun.get('node').put(updates);

// Increase batching
const gun = Gun({
  gap: 50, // Wait 50ms before sending
  pack: 10000 // 10KB batches
});

Issue: CPU Spikes

Cause: Large JSON parsing, synchronous operations Solution:

// Use async JSON parser
require('gun/lib/yson');

// Reduce processing per tick
const gun = Gun({
  puff: 3 // Process fewer messages per tick
});

Best Practices

Use .once() for one-time reads: Avoid unnecessary subscriptions
Batch writes: Group multiple updates together
Limit graph depth: Keep data structures flat
Configure memory limits: Prevent unbounded growth
Enable async JSON parsing: Add gun/lib/yson.js
Monitor statistics: Track performance metrics
Profile regularly: Identify bottlenecks early
Use super peer mode: Optimize relay peers
Implement pagination: Don’t load entire datasets
Unsubscribe when done: Clean up listeners

Performance Checklist

Next Steps

Understand CAP Theorem tradeoffs
Learn about Conflict Resolution
Configure Networking for your topology
Deploy to Production

Get Started

Core Concepts

API Reference

Security (SEA)

Storage Adapters

Advanced

Integration Guides

Documentation Index

​Performance Characteristics

​Throughput

​Memory Efficiency

​Optimization Strategies

​1. Minimize Subscriptions

​2. Batch Writes

​3. Use Property Paths

​4. Limit Graph Depth

​5. Configure Message Batching

​6. Enable Super Peer Mode

​Storage Performance

​In-Memory Only

​File System Storage

​RAD Storage

​S3 Storage

​Network Performance

​WebSocket vs HTTP

​Connection Pooling

​Multicast for Local Networks

​JSON Performance

​Async JSON Parsing

​Warning System

​CPU Optimization

​Event Loop Scheduling

​Configurable Processing Rate

​Monitoring Performance

​Enable Statistics

​Message Counters

​Latency Tracking

​Profiling

​Node.js Profiling

​Browser Profiling

​Benchmarking

​Write Performance

​Read Performance

​Production Optimizations

​1. Use a CDN

​2. Enable Compression

​3. Use Process Clustering

​4. Configure Timeouts

​5. Limit Message Size

​Common Performance Issues

​Issue: High Memory Usage

​Issue: Slow Initial Load

​Issue: Network Congestion

​Issue: CPU Spikes

​Best Practices

​Performance Checklist

​Next Steps

Build docs developers (and LLMs) love