# LiveMap
`LiveMap` is a synchronized key/value data structure that stores [primitive values](https://ably.com/docs/liveobjects/concepts/objects#primitive-types), such as numbers, strings, booleans, binary data, JSON-serializable objects or arrays and other live [object types](https://ably.com/docs/liveobjects/concepts/objects#object-types). It ensures that all updates are correctly applied and synchronized across clients in realtime, automatically resolving conflicts with last-write-wins (LWW) semantics.
You interact with `LiveMap` through a [PathObject](https://ably.com/docs/liveobjects/concepts/path-object) or by obtaining a specific [Instance](https://ably.com/docs/liveobjects/concepts/instance).
## Create a map
Create a `LiveMap` using the `LiveMap.create()` static method and assign it to a path:
```javascript
import { LiveMap } from 'ably/liveobjects';
// Create an empty map
await myObject.set('settings', LiveMap.create());
// Create a map with initial data
await myObject.set('user', LiveMap.create({
name: 'Alice',
score: 42,
active: true
}));
// Create nested maps
await myObject.set('config', LiveMap.create({
theme: LiveMap.create({
color: 'dark',
fontSize: 14
})
}));
```
`LiveMap.create()` returns a value type that describes the initial data for a new map. The actual object is created when assigned to a path. Each assignment creates a distinct object with its own unique ID:
```javascript
const mapValue = LiveMap.create({ theme: 'dark' });
// Each assignment creates a different object
await myObject.set('map1', mapValue);
await myObject.set('map2', mapValue);
// map1 and map2 are different objects with different IDs
const id1 = myObject.get('map1').instance()?.id();
const id2 = myObject.get('map2').instance()?.id();
console.log(id1 === id2); // false
```
## Get map values
Access a `LiveMap` through a [PathObject](https://ably.com/docs/liveobjects/concepts/path-object) for path-based operations, or obtain a specific [Instance](https://ably.com/docs/liveobjects/concepts/instance) to work with the underlying object directly. Use the `get()` method to navigate to entries within the map.
What you can do with the result depends on the type of value stored in the entry:
- For entries containing [primitive values](https://ably.com/docs/liveobjects/concepts/objects#primitive-types) or [`LiveCounter`](https://ably.com/docs/liveobjects/counter) objects, use the `value()` method to get the current value.
- For entries containing nested `LiveMap` objects, use `get()` to continue navigating deeper into the structure.
```javascript
const myObject = await channel.object.get();
// PathObject access: path-based operations that resolve at runtime
const theme = myObject.get('settings').get('theme'); // settings holds a LiveMap with a 'theme' key
console.log(theme.value()); // e.g. 'dark'
const visits = myObject.get('visits'); // visits holds a LiveCounter
console.log(visits.value()); // e.g. 5
// Instance access: reference to a specific map object
const settingsInstance = myObject.get('settings').instance();
console.log(settingsInstance?.get('theme')?.value()); // e.g. 'dark' (primitive string)
```
## Get compact object
Get a JavaScript object representation of the map using the `compact()` or `compactJson()` methods:
```javascript
// Get a PathObject to a LiveMap stored in 'settings'
const settings = myObject.get('settings');
console.log(settings.compact());
// e.g. { theme: 'dark', fontSize: 14, notifications: true }
// Get the Instance of a LiveMap stored in 'settings'
const settingsInstance = myObject.get('settings').instance();
console.log(settingsInstance?.compact());
// e.g. { theme: 'dark', fontSize: 14, notifications: true }
```
## Set map values
Set a value for a key in the map using the `set()` method. You can store primitive values or other live [object types](https://ably.com/docs/liveobjects/concepts/objects#object-types):
```javascript
// PathObject: set values at path
await myObject.get('settings').set('theme', 'dark');
await myObject.get('settings').set('fontSize', 14);
await myObject.get('settings').set('notifications', true);
// Set a nested map
await myObject.get('settings').set('advanced', LiveMap.create({
debugMode: false,
logLevel: 'info'
}));
// Set a counter
await myObject.get('settings').set('visits', LiveCounter.create(0));
// Instance: set values on specific map instance
const settingsInstance = myObject.get('settings').instance();
await settingsInstance?.set('theme', 'dark');
await settingsInstance?.set('fontSize', 14);
```
## Remove a key
Remove a key from the map using the `remove()` method:
```javascript
// PathObject: remove key at path
await myObject.get('settings').remove('oldSetting');
// Instance: remove key on specific map instance
const settingsInstance = myObject.get('settings').instance();
await settingsInstance?.remove('oldSetting');
```
## Get map size
Get the number of keys in the map using the `size()` method:
```javascript
// PathObject: get size at path
const settings = myObject.get('settings');
console.log(settings.size()); // e.g. 5
// Instance: get size of specific map instance
const settingsInstance = myObject.get('settings').instance();
console.log(settingsInstance?.size()); // e.g. 5
```
## Enumerate entries
Iterate over the map's keys, values, or entries. When iterating using a `PathObject`, values are returned as a `PathObject` for the nested path. When iterating using an `Instance`, values are returned as an `Instance` for the entry:
```javascript
// PathObject: iterate with PathObject values
const settings = myObject.get('settings');
for (const [key, value] of settings.entries()) {
console.log(`${key}:`, value.value());
}
for (const key of settings.keys()) {
console.log('Key:', key);
}
for (const value of settings.values()) {
console.log('Value:', value.value());
}
// Instance: iterate with Instance values
const settingsInstance = myObject.get('settings').instance();
if (settingsInstance) {
for (const [key, valueInstance] of settingsInstance.entries()) {
console.log(`${key}:`, valueInstance.value());
}
for (const key of settingsInstance.keys()) {
console.log('Key:', key);
}
for (const value of settingsInstance.values()) {
console.log('Value:', value.value());
}
}
```
## Batch multiple operations
Group multiple map operations into a single atomic message using the `batch()` method. All operations within the batch are sent as one logical unit which succeed or fail together:
```javascript
// PathObject: batch operations on map at path
await myObject.get('settings').batch((ctx) => {
ctx.set('theme', 'dark');
ctx.set('fontSize', 14);
ctx.set('notifications', true);
ctx.remove('oldSetting');
});
// Instance: batch operations on specific map instance
const settingsInstance = myObject.get('settings').instance();
await settingsInstance?.batch((ctx) => {
ctx.set('theme', 'dark');
ctx.set('fontSize', 14);
});
```
## Subscribe to updates
Subscribe to `LiveMap` updates to receive realtime notifications when the map changes.
`PathObject` subscriptions observe a location and automatically track changes even if the `LiveMap` instance at that path is replaced. `Instance` subscriptions track a specific `LiveMap` instance, following it even if it moves in the channel object.
```javascript
// PathObject: observe location - tracks changes even if map instance is replaced
const settings = myObject.get('settings');
const { unsubscribe } = settings.subscribe(() => {
console.log('Settings:', settings.compact());
});
// Later, stop listening to changes
unsubscribe();
// Instance: track specific map instance - follows it even if moved in object tree
const settingsInstance = myObject.get('settings').instance();
if (settingsInstance) {
const { unsubscribe } = settingsInstance.subscribe(() => {
console.log('Settings:', settingsInstance.compact());
});
// Later, stop listening to changes
unsubscribe();
}
```
Alternatively, use the `subscribeIterator()` method for an async iterator syntax:
```javascript
// PathObject: observe location - tracks changes even if map instance is replaced
const settings = myObject.get('settings');
for await (const _ of settings.subscribeIterator()) {
console.log('Settings:', settings.compact());
if (someCondition) {
break; // Unsubscribes
}
}
// Instance: track specific map instance - follows it even if moved in object tree
const settingsInstance = myObject.get('settings').instance();
if (settingsInstance) {
for await (const _ of settingsInstance.subscribeIterator()) {
console.log('Settings:', settingsInstance.compact());
if (someCondition) {
break; // Unsubscribes
}
}
}
```
## Create LiveMap
A `LiveMap` instance can be created using the `channel.objects.createMap()` method. It must be stored inside another `LiveMap` object that is reachable from the [root object](https://ably.com/docs/liveobjects/concepts/objects#root-object).
`channel.objects.createMap()` is asynchronous, as the client sends the create operation to the Ably system and waits for an acknowledgment of the successful map creation.
```swift
let map = try await channel.objects.createMap()
try await root.set(key: "myMap", value: .liveMap(map))
```
```java
LiveMap map = channel.getObjects().createMap();
root.set("myMap", LiveMapValue.of(map));
```
Optionally, you can specify an initial key/value structure when creating the map:
```swift
// Pass a Dictionary reflecting the initial state
let map = try await channel.objects.createMap(entries: ["foo": "bar", "baz": 42])
// You can also pass other objects as values for keys
try await channel.objects.createMap(entries: ["nestedMap": .liveMap(map)])
```
```java
// Pass a Map with initial key/value pairs
Map entries = Map.of(
"foo", LiveMapValue.of("bar"),
"baz", LiveMapValue.of(42)
);
LiveMap map = channel.getObjects().createMap(entries);
// You can also pass other objects as values for keys
Map nestedEntries = Map.of(
"nestedMap", LiveMapValue.of(map)
);
channel.getObjects().createMap(nestedEntries);
```
## Get value for a key
Get the current value for a key in a map using the `LiveMap.get()` method:
```swift
let value = try map.get(key: "my-key")
print("Value for my-key: \(String(describing: value))")
```
```java
System.out.println("Value for my-key: " + map.get("my-key").getValue());
```
## Subscribe to data updates
You can subscribe to data updates on a map to receive realtime changes made by you or other clients.
Subscribe to data updates on a map using the `LiveMap.subscribe()` method:
```swift
try map.subscribe { update, _ in
do {
print("Map updated: \(try map.entries)")
} catch {
// Error handling of map.entries omitted for brevity
}
print("Update details: \(update)")
}
```
```java
map.subscribe((mapUpdate) -> {
System.out.println("Map updated: " + map.entries());
System.out.println("Update details: " + mapUpdate.getUpdate());
});
```
The update object provides details about the change, listing the keys that were changed and indicating whether they were updated (value changed) or removed from the map.
It may also include the client ID of the client that made the change, if the change can be attributed to a specific client. For example, the client ID may be missing if the update was triggered by data resynchronization after a disconnection and the change occurred while the client was offline.
Example structure of an update object when the key `foo` is updated and the key `bar` is removed, made by a client with the ID `my-client`:
```json
{
"update": {
"foo": "updated",
"bar": "removed"
},
"clientId": "my-client"
}
```
### Unsubscribe from data updates
Use the `unsubscribe()` function returned in the `subscribe()` response to remove a map update listener:
```swift
// Initial subscription
let subscriptionResponse = try map.subscribe { _, _ in
print("Map updated")
}
// To remove the listener
subscriptionResponse.unsubscribe()
```
```java
// Initial subscription
ObjectsSubscription subscription = map.subscribe((mapUpdate) ->
System.out.println("Map updated")
);
// To remove the listener
subscription.unsubscribe();
```
To remove a map update listener from _inside_ the listener function, you can call `unsubscribe()` on the subscription response that is passed as the second argument to the listener function:
```swift
try map.subscribe { _, subscriptionResponse in
// Remove the listener so that this callback
// no longer gets called
subscriptionResponse.unsubscribe()
}
```
Use the `LiveMap.unsubscribe()` method to deregister a provided listener:
```java
// Initial subscription
LiveMap.Listener listener = (mapUpdate) ->
System.out.println("Map updated");
map.subscribe(listener);
// To remove the listener
map.unsubscribe(listener);
```
Use the `LiveMap.unsubscribeAll()` method to deregister all map update listeners:
```swift
map.unsubscribeAll();
```
```java
map.unsubscribeAll();
```
## Set keys in a LiveMap
Set a value for a key in a map by calling `LiveMap.set()``LiveMap.set(key:value:)`. This operation is synchronized across all clients and triggers data subscription callbacks for the map, including on the client making the request.
Keys in a map can contain numbers, strings, booleans, buffers`Data`, JSON-serializable objects or arrays and other `LiveMap` and `LiveCounter` objects.
This operation is asynchronous, as the client sends the corresponding update operation to the Ably system and waits for acknowledgment of the successful map key update.
```swift
try await map.set(key: "foo", value: "bar")
try await map.set(key: "baz", value: 42)
// Can also set a reference to another object
let counter = try await channel.objects.createCounter()
try await map.set(key: "counter", value: .liveCounter(counter))
```
```java
map.set("foo", LiveMapValue.of("bar"));
map.set("baz", LiveMapValue.of(42));
// Can also set a reference to another object
LiveCounter counter = channel.getObjects().createCounter();
map.set("counter", LiveMapValue.of(counter));
```
## Remove a key from a LiveMap
Remove a key from a map by calling `LiveMap.remove()``LiveMap.remove(key:)`. This operation is synchronized across all clients and triggers data subscription callbacks for the map, including on the client making the request.
This operation is asynchronous, as the client sends the corresponding remove operation to the Ably system and waits for acknowledgment of the successful map key removal.
```swift
try await map.remove(key: "foo")
```
```java
map.remove("foo");
```
## Get the number of entries in a LiveMap
Get the number of entries in a map using `LiveMap.size``LiveMap.size()`:
```swift
let map = try await channel.objects.createMap(entries: ["foo": "bar", "baz": "qux"])
print(try map.size) // e.g. 2
```
```java
LiveMap map = channel.getObjects().createMap(Map.of(
"foo", LiveMapValue.of("bar"),
"baz", LiveMapValue.of("qux")
));
System.out.println(map.size()); // e.g. 2
```
## Iterate over key/value pairs
Iterate over key/value pairs, keys or values using the `LiveMap.entries()`, `LiveMap.keys()` and `LiveMap.values()` methods`LiveMap.entries`, `LiveMap.keys` and `LiveMap.values` properties respectively.
These properties are all `Array`-valued. Note that they do not guarantee that entries are returned in insertion order.
These methods return a map iterator for convenient traversal. These methods do not guarantee that entries are returned in insertion order.
```swift
for (key, value) in try map.entries {
print("Key: \(key), Value: \(value)")
}
for key in try map.keys {
print("Key: \(key)")
}
for value in try map.values {
print("Value: \(value)")
}
```
```java
for (Map.Entry entry : map.entries()) {
System.out.println("Key: " + entry.getKey());
System.out.println("Value: " + entry.getValue().getValue());
}
for (String key : map.keys()) {
System.out.println("Key: " + key);
}
for (LiveMapValue value : map.values()) {
System.out.println("Value: " + value.getValue());
}
```
## Subscribe to lifecycle events
Subscribe to lifecycle events on a map using the `LiveMap.on()``LiveMap.on(event:callback:)` method:
```swift
map.on(event: .deleted) { _ in
print("Map has been deleted")
}
```
```java
map.on(ObjectLifecycleEvent.DELETED, (lifecycleEvent) -> {
System.out.println("Map has been deleted");
});
```
Read more about [objects lifecycle events](https://ably.com/docs/liveobjects/lifecycle#objects).
### Unsubscribe from lifecycle events
Use the `off()` function returned in the `on()` response to remove a lifecycle event listener:
```swift
// Initial subscription
let eventResponse = map.on(event: .deleted) { _ in
print("Map deleted")
}
// To remove the listener
eventResponse.off()
```
```java
// Initial subscription
ObjectsSubscription subscription = map.on(ObjectLifecycleEvent.DELETED, (lifecycleEvent) ->
System.out.println("Map deleted")
);
// To remove the listener
subscription.unsubscribe();
```
Use the `LiveMap.off()` method to deregister a provided lifecycle event listener:
```java
// Initial subscription
ObjectLifecycleChange.Listener listener = (lifecycleEvent) ->
System.out.println("Map deleted");
map.on(ObjectLifecycleEvent.DELETED, listener);
// To remove the listener
listener.unsubscribe()
// Alternatively, remove the shared listener from all event registrations
map.off(listener);
```
Use the `LiveMap.offAll()` method to deregister all lifecycle event listeners:
```swift
map.offAll()
```
```java
map.offAll();
```
## Create nested structures
A `LiveMap` can store other `LiveMap` or `LiveCounter` objects as values for its keys, enabling you to build complex, hierarchical object structure. This enables you to represent complex data models in your applications while ensuring realtime synchronization across clients.
```swift
// Create a hierarchy of objects using LiveMap
let counter = try await channel.objects.createCounter()
let map = try await channel.objects.createMap(entries: ["nestedCounter": .liveCounter(counter)])
let outerMap = try await channel.objects.createMap(entries: ["nestedMap": .liveMap(map)])
try await root.set(key: "outerMap", value: .liveMap(outerMap))
// resulting structure:
// root (LiveMap)
// └── outerMap (LiveMap)
// └── nestedMap (LiveMap)
// └── nestedCounter (LiveCounter)
```
```java
// Create a hierarchy of objects using LiveMap
LiveCounter counter = channel.getObjects().createCounter();
LiveMap map = channel.getObjects().createMap(Map.of(
"nestedCounter", LiveMapValue.of(counter)
));
LiveMap outerMap = channel.getObjects().createMap(Map.of(
"nestedMap", LiveMapValue.of(map)
));
root.set("outerMap", LiveMapValue.of(outerMap));
// resulting structure:
// root (LiveMap)
// └── outerMap (LiveMap)
// └── nestedMap (LiveMap)
// └── nestedCounter (LiveCounter)
```