.map()

The .map() method iterates over all properties in a collection, calling a callback for each item. It’s essential for working with sets, lists, and any object with dynamic keys.

Signature

gun.map()
gun.map(callback)
gun.map(filter)

Parameters

function

Experimental: Function called for each item to transform the data.Signature: function(data, key, message, event)

data - The item data
key - The item’s key/ID
message - Full message object
event - Event control object

Return value:

Return the data to pass it through unchanged
Return modified data to transform it
Return undefined to filter out the item
Return a GUN reference to chain to it

object

Lexical filter object to match specific keys

Show properties

string | RegExp

Pattern to match against keys

Return Value

Returns a GUN chain that emits each item individually. Chain with .on() or .once() to process items.

Examples

Basic Iteration

// Display all todos
gun.get('todos').map().on(function(todo, key){
  console.log('Todo ' + key + ':', todo.text)
})

// One-time read of all items
gun.get('todos').map().once(function(todo, key){
  console.log('Todo ' + key + ':', todo.text)
})

Realtime List Rendering

// Render a todo list that updates in realtime
var todosEl = document.getElementById('todos')

gun.get('todos').map().on(function(todo, id){
  var li = document.getElementById(id) || document.createElement('li')
  li.id = id
  li.textContent = todo.text
  
  if(todo.done){
    li.style.textDecoration = 'line-through'
  }
  
  if(!li.parentNode){
    todosEl.appendChild(li)
  }
})

Nested Maps

// Iterate over users and their posts
gun.get('users').map().on(function(user, userId){
  console.log('User:', user.name)
  
  gun.get('users').get(userId).get('posts').map().on(function(post){
    console.log('  Post:', post.title)
  })
})

Transform with Callback (Experimental)

// Filter and transform items
gun.get('todos').map(function(todo, key){
  // Skip completed todos
  if(todo.done) return undefined
  
  // Transform the data
  return {
    id: key,
    text: todo.text,
    priority: todo.priority || 'normal'
  }
}).on(function(transformed){
  console.log('Active todo:', transformed)
})

Lexical Filtering

// Only match keys starting with 'user:'
gun.get('data').map({'.' : 'user:*'}).on(function(user){
  console.log('User:', user)
})

// Match specific pattern
gun.get('events').map({'.' : /2024-.*/}).on(function(event){
  console.log('2024 event:', event)
})

Chat Application

var messagesEl = document.getElementById('messages')

// Listen for new messages
gun.get('chat/room1').get('messages').map().on(function(msg, id){
  var div = document.getElementById(id)
  if(!div){
    div = document.createElement('div')
    div.id = id
    messagesEl.appendChild(div)
  }
  
  div.innerHTML = `
    <strong>${msg.from}</strong>: ${msg.text}
    <span class="time">${new Date(msg.timestamp).toLocaleTimeString()}</span>
  `
})

// Send a message
gun.get('chat/room1').get('messages').set({
  from: 'alice',
  text: 'Hello everyone!',
  timestamp: Date.now()
})

Count Items

// Count items in a collection
var count = 0
gun.get('items').map().once(function(){
  count++
})

setTimeout(function(){
  console.log('Total items:', count)
}, 100)

Filter and Sort

// Collect and sort items
var items = []

gun.get('products').map().once(function(product, key){
  items.push({
    id: key,
    name: product.name,
    price: product.price
  })
})

setTimeout(function(){
  // Sort by price
  items.sort((a, b) => a.price - b.price)
  items.forEach(item => console.log(item.name, item.price))
}, 100)

Implementation Details

From the source code (map.js:16-37):

Gun.chain.map = function(cb, opt, t){
  var gun = this, cat = gun._, lex, chain;
  if(Object.plain(cb)){ lex = cb['.']? cb : {'.': cb}; cb = u }
  if(!cb){
    if(chain = cat.each){ return chain }
    (cat.each = chain = gun.chain())._.lex = lex || chain._.lex || cat.lex;
    chain._.nix = gun.back('nix');
    gun.on('in', map, chain._);
    return chain;
  }
  // ... callback version (experimental)
}

function map(msg){ this.to.next(msg);
  var cat = this.as, gun = msg.$, at = gun._, put = msg.put, tmp;
  if(!at.soul && !msg.$$){ return }
  if((tmp = cat.lex) && !String.match(msg.get|| (put||'')['.'], tmp['.'] || tmp['#'] || tmp)){ return }
  Gun.on.link(msg, cat);
}

The .map() method:

Creates a new chain that listens for all child updates
Fires the chain callback for each property/item
Optionally filters using lexical matching
Experimental: transforms data when callback is provided
Automatically follows links to nested data

Map vs Iteration

Feature	.map()	.get(key)
Purpose	Iterate all items	Access specific item
Keys	Dynamic/unknown	Known
Usage	Collections, sets	Single values
Returns	Chain per item	Single chain

Performance Considerations

// ❌ Inefficient - creates many subscriptions
gun.get('items').map().on(function(item){
  gun.get('users').map().on(function(user){
    // N × M subscriptions!
  })
})

// ✅ Better - limit nested subscriptions
gun.get('items').map().once(function(item){
  gun.get('users').get(item.userId).once(function(user){
    console.log(user)
  })
})

Empty Sets

// Map over empty set does nothing
gun.get('emptySet').map().on(function(item){
  // Never called if set is empty
})

// To detect empty sets
var found = false
gun.get('mySet').map().once(function(){
  found = true
})

setTimeout(function(){
  if(!found){
    console.log('Set is empty')
  }
}, 100)

Reuse Map Chain

// Reusable map reference
var allTodos = gun.get('todos').map()

// Use it multiple times
allTodos.once(function(todo){
  console.log('Todo:', todo)
})

allTodos.on(function(todo){
  updateUI(todo)
})

// Both callbacks receive the same data

Notes

.map() without arguments returns a chain for iteration
Use .once() after .map() for one-time iteration
Use .on() after .map() for realtime updates
The callback version (with function argument) is experimental
Map automatically resolves links to the linked data
No guaranteed iteration order - items arrive as they’re loaded
For empty collections, callbacks never fire
Map is perfect for working with .set() collections

Get Started

Core Concepts

API Reference

Security (SEA)

Storage Adapters

Advanced

Integration Guides

.map()

.map()

Signature

Parameters

Return Value

Examples

Basic Iteration

Realtime List Rendering

Nested Maps

Transform with Callback (Experimental)

Lexical Filtering

Chat Application

Count Items

Filter and Sort

Implementation Details

Map vs Iteration

Performance Considerations

Empty Sets

Reuse Map Chain

Notes

​.map()

​Signature

​Parameters

​Return Value

​Examples

​Basic Iteration

​Realtime List Rendering

​Nested Maps

​Transform with Callback (Experimental)

​Lexical Filtering

​Chat Application

​Count Items

​Filter and Sort

​Implementation Details

​Map vs Iteration

​Performance Considerations

​Empty Sets

​Reuse Map Chain

​Notes

.map()

Signature

Parameters

Return Value

Examples

Basic Iteration

Realtime List Rendering

Nested Maps

Transform with Callback (Experimental)

Lexical Filtering

Chat Application

Count Items

Filter and Sort

Implementation Details

Map vs Iteration

Performance Considerations

Empty Sets

Reuse Map Chain

Notes