Ably JavaScript SDK

In v2.16+, the API entrypoint has changed from channel.objects to channel.object. Instead of getRoot(), use channel.object.get() to obtain a PathObject.

PathObject operations resolve the path at runtime. This means:

• Obtaining a PathObject never fails, even if the path doesn't exist yet.
• Access methods (like .value() or .entries()) return empty defaults (e.g., undefined or an empty iterator) if the path is invalid at runtime.
• Mutation methods (like .set() or .increment()) will throw errors if the path does not resolve to the expected type at runtime.

You can navigate nested structures by chaining .get() calls or using .at('path.to.key').

// Navigate nested structures
const shape = myObject.get('shape');
const colour = myObject.get('shape').get('colour');

// Use .at() for fully-qualified paths
const border = myObject.at('shape.colour.border');

// Get the string path of a location
const path = myObject.get('shape').get('colour').get('border').path();

Use the ChannelProvider component to define a specific channel for a subtree of your application. This allows child components to use channel-based hooks without explicitly passing the channel name.

Channel Resolution:

• If a hook (like useChannel) is called without a channelName, it resolves to the nearest enclosing ChannelProvider.
• When providers are nested, the nearest one wins.
• Note on ablyId: Channel resolution is scoped by ablyId. If a ChannelProvider uses a non-default ablyId, you must pass that same ablyId to the hook to resolve the channel correctly.
• SSR Warning: React hooks are designed for client-side use. Ensure components using these hooks are only rendered on the client side during Server-Side Rendering.

<ChannelProvider channelName="your-channel-name">
  <Component />
</ChannelProvider>

// Inside Component, the name is inferred:
const { channel } = useChannel((message) => {
  console.log(message);
});

In ably-js v2.16 and later, the LiveObjects API shifted from an instance-based model to a path-based model using PathObject.

Instead of interacting directly with specific LiveMap or LiveCounter instances, you now interact with a PathObject, which represents a path to a location within your channel's object hierarchy.

Key differences and benefits:

• Runtime Resolution: Operations are evaluated against the current value at a path at the moment the operation is invoked, rather than when the object was created. This makes code more resilient to changes in the object structure.
• Resilient Subscriptions: You subscribe to paths rather than specific object instances. This prevents subscriptions from breaking if an object at a specific path is replaced with a new instance.
• Simplified Hierarchy: You can create deeply nested structures in a single operation without manually managing child objects or worrying about orphaned instances.
• Null Safety: The path-based approach removes the need for explicit null checks when traversing hierarchies, as the path resolves dynamically.

The modular variant allows you to build a tree-shakable client by importing only the necessary functionality. This is ideal for optimizing bundle size in web applications.

To use it, import BaseRealtime and specific plugins from ably/modular. You must provide at least one HTTP request implementation (FetchRequest or XHRRequest) and at least one realtime transport implementation (WebSocketTransport or XHRPolling).

Note: The modular variant performs less logging than the default variant to further reduce size. It only logs errors (logLevel 1) and select network events.

import { BaseRealtime, WebSocketTransport, FetchRequest, RealtimePresence } from 'ably/modular';

const client = new BaseRealtime({
  key: 'YOUR_ABLY_API_KEY', // Replace with a real key from the Ably dashboard
  plugins: {
    WebSocketTransport,
    FetchRequest,
    RealtimePresence,
  },
});

Before upgrading to v2, if you are using the callbacks variant of v1, you must switch to the promise-based variant.

1. Change the import/instantiation:

• require('ably/callbacks') $\rightarrow$ require('ably/promises')
• new Ably.Realtime.Callbacks(...) $\rightarrow$ new Ably.Realtime.Promise(...)

2. Update method calls: Methods that previously took a callback (err, result) as the last argument should now be called using await or .then()/.catch().

// v1 Callbacks style
channel.history({ direction: 'forwards' }, (err, paginatedResult) => {
  if (err) return;
  // use paginatedResult
});

// v1 Promises style (Required before v2 upgrade)
// Option A: async/await
try {
  const paginatedResult = await channel.history({ direction: 'forwards' });
} catch (err) {
  // handle error
}

// Option B: .then()
channel.history({ direction: 'forwards' })
  .then((paginatedResult) => { /* use result */ })
  .catch((err) => { /* handle error */ });

Note: In v1, Crypto.generateRandomKey() is an exception; it remains callback-based even in the v1 promise variant. In v2, it becomes promise-based.

// v1 Callbacks style
channel.history({ direction: 'forwards' }, (err, paginatedResult) => {
  if (err) {
    // Perform some sort of error handling
    return;
  }

  // Make use of paginatedResult
});

// v1 Promises style (Required before v2 upgrade)
// Option A: async/await
try {
  const paginatedResult = await channel.history({ direction: 'forwards' });
  // Make use of paginatedResult
} catch (err) {
  // Perform some sort of error handling
}

// Option B: .then()
channel
  .history({ direction: 'forwards' })
  .then((paginatedResult) => {
    // Make use of paginatedResult
  })
  .catch((err) => {
    // Perform some sort of error handling
  });