LiveCounter

LiveCounter is a synchronized numerical counter that supports increment and decrement operations. It ensures that all updates are correctly applied and synchronized across users in realtime, preventing inconsistencies when multiple users modify the counter value simultaneously.

A LiveCounter instance can be created using the channel.objects.createCounter() method. It must be stored inside a LiveMap object that is reachable from the root object .

channel.objects.createCounter() is asynchronous, as the client sends the create operation to the Ably system and waits for an acknowledgment of the successful counter creation.

JavaScript v2.9
const counter = await channel.objects.createCounter(); await root.set('counter', counter);
Copied!

Optionally, you can specify an initial value when creating the counter:

JavaScript v2.9
const counter = await channel.objects.createCounter(100); // Counter starts at 100
Copied!

Get the current value of a counter using the LiveCounter.value() method:

JavaScript v2.9
console.log('Counter value:', counter.value());
Copied!

You can subscribe to data updates on a counter to receive realtime changes made by you or other clients.

Subscribe to data updates on a counter using the LiveCounter.subscribe() method:

JavaScript v2.9
counter.subscribe((update) => { console.log('Counter updated:', counter.value()); console.log('Update details:', update); });
Copied!

The update object provides details about the change, such as the amount by which the counter value was changed.

Example structure of an update object when the counter was incremented by 5:

{ { "amount": 5 } }
Copied!

Or decremented by 10:

{ { "amount": -10 } }
Copied!

Use the unsubscribe() function returned in the subscribe() response to remove a counter update listener:

JavaScript v2.9
// Initial subscription const { unsubscribe } = counter.subscribe(() => console.log(counter.value())); // To remove the listener unsubscribe();
Copied!

Use the LiveCounter.unsubscribe() method to deregister a provided listener:

JavaScript v2.9
// Initial subscription const listener = () => console.log(counter.value()); counter.subscribe(listener); // To remove the listener counter.unsubscribe(listener);
Copied!

Use the LiveCounter.unsubscribeAll() method to deregister all counter update listeners:

JavaScript v2.9
counter.unsubscribeAll();
Copied!

Update the counter value by calling LiveCounter.increment() or LiveCounter.decrement(). These operations are synchronized across all clients and trigger data subscription callbacks for the counter, including on the client making the request.

These operations are asynchronous, as the client sends the corresponding update operation to the Ably system and waits for acknowledgment of the successful counter update.

JavaScript v2.9
await counter.increment(5); // Increase value by 5 await counter.decrement(2); // Decrease value by 2
Copied!

Subscribe to lifecycle events on a counter using the LiveCounter.on() method:

JavaScript v2.9
counter.on('deleted', () => { console.log('Counter has been deleted'); });
Copied!

Read more about objects lifecycle events.

Use the off() function returned in the on() response to remove a lifecycle event listener:

JavaScript v2.9
// Initial subscription const { off } = counter.on(('deleted') => console.log('Counter deleted')); // To remove the listener off();
Copied!

Use the LiveCounter.off() method to deregister a provided lifecycle event listener:

JavaScript v2.9
// Initial subscription const listener = () => console.log('Counter deleted'); counter.on('deleted', listener); // To remove the listener counter.off('deleted', listener);
Copied!

Use the LiveCounter.offAll() method to deregister all lifecycle event listeners:

JavaScript v2.9
counter.offAll();
Copied!
Select...