Operations

LiveObjects operations define how object data is updated and synchronized across multiple clients. This document explains the key concepts you need to know when working with operations.

Each object type supports specific operations that modify the object’s data.

LiveMap supports the following operations:

• set: Set a value for a key
• remove: Remove a key and its value

The value of an entry in a LiveMap instance can be a primitive type or a reference to another object.

JavaScript
JavaScript v2.9

// Set a value for a key
await map.set('username', 'alice');


// Remove a key
await map.remove('username');

Copy
Copied!

LiveCounter supports the following operations:

• increment: Increment the counter by a specified amount
• decrement: Decrement the counter by a specified amount

The amount is a double-precision floating-point number, which is the same as underlying type of a LiveCounter value.

JavaScript
JavaScript v2.9

// Increment counter by 5
await counter.increment(5);


// Decrement counter by 2
await counter.decrement(2);

Copy
Copied!

Create operations are used to instantiate new objects of a given type.

A create operation can optionally specify an initial value for the object.

JavaScript
JavaScript v2.9

// Create a map with initial values
const userMap = await channel.objects.createMap({
  username: 'alice',
  status: 'online'
});


// Create a counter with initial value
const scoreCounter = await channel.objects.createCounter(100);

Copy
Copied!

When a create operation is processed, an object ID for the new object instance is automatically generated for the object.

Every operation is expressed relative to a specific object instance, identified by its object ID , which determines which object the operation is applied to.

When using a client library object IDs are handled automatically, allowing you work directly with object references:

JavaScript
JavaScript v2.9

// The published operation targets the object ID of the `userMap` object instance
await userMap.set('username', 'alice');

Copy
Copied!

Therefore it is important that you obtain an up-to-date object instance before performing operations on an object. For example, you can subscribe to a LiveMap instance to ensure you always have an up-to-date reference to any child objects in the map:

JavaScript
JavaScript v2.9

const root = await channel.objects.getRoot();


let myCounter = root.get('myCounter');
root.subscribe(() => { myCounter = root.get('myCounter'); });


// before incrementing, ensure we have an up-to-date object reference if
// the counter instance at the 'myCounter' key in the root map changes
await myCounter.increment(1);

Copy
Copied!

In the REST API , this relationship is made explicit:

curl -X POST https://rest.ably.io/channels/my-channel/objects \
 -u "<loading API key, please wait>"
 -H "Content-Type: application/json" \
 --data \
'{
  "operation": "MAP_SET",
  "objectId": "root",
  "data": {"key": "username", "value": {"string": "alice"}}
}'
API Key:
Demo Only
Copy
Copied!

Batch operations can be used to batch a set of operations together:

• Multiple operations are grouped into a single atomic unit
• All operations in the batch either succeed together or fail together
• Operations in a batch are sent as a single message
• No operations from other clients can be interleaved within a batch