Ably Models SDK
Overview
The Ably Models SDK is a key component of the LiveSync product that lets you stream realtime updates from your database at scale to frontend clients.
![LiveSync Diagram LiveSync Diagram](https://github.com/ably-labs/models/raw/HEAD/docs/images/what-is-livesync.png)
The Models SDK is a frontend library that simplifies subscribing to the changes in data models, applying optimistic updates and merging them with confirmed updates. It is a standalone SDK built on Ably’s JavaScript SDK with full TypeScript support.
The Database Connector and Ably Channels are the other two components of LiveSync that help publish changes from your database to frontend clients.
A model represents a data model of a specific part of your frontend application. Each frontend client can have multiple data models within the same application.
![Models SDK Diagram Models SDK Diagram](https://github.com/ably-labs/models/raw/HEAD/docs/images/models-diagram.png)
When creating a new Model using the Models SDK you provide two functions to the Model a sync()
function and a merge()
function:
- The
sync(
) function is used by the SDK to retrieve the current state of the data model from your backend. - The
merge()
function is used by the SDK to merge state change events published by the Database Connector with the existing frontend state in the Model.
You can use the Models SDK as a standalone library to merge new update events with existing frontend state, but the SDK works best as part of LiveSync.
The data models as part of the Models SDK remain synchronized with the state of your database, in realtime. You can easily integrate this SDK into your project regardless of which frontend framework you use.
Development Status
LiveSync, and the Models SDK, is in public alpha so that you can explore its capabilities. Your feedback will help prioritize improvements and fixes for later releases. The features in this release have been built to work under real-world situations and load, and for real-world use-cases, but there may still be some rough edges in this alpha.
Quickstart
Prerequisites
To begin, you will need the following:
- An Ably account. You can sign up for free.
- An Ably API key. You can create API keys in an app within your Ably account.
Installation and authentication
Install the Ably JavaScript SDK and the Realtime Data Models SDK:
npm install ably @ably-labs/models
Though you can test your installation and authentication with basic authentication, we strongly recommend token authentication for in production environments.
Instantiation
To instantiate the Realtime Data Models SDK, create an Ably client and pass it into the ModelsClient constructor:
import ModelsClient from '@ably-labs/models';
import { Realtime } from 'ably';
const ably = new Realtime({ key: 'YOUR_ABLY_API_KEY' });
const modelsClient = new ModelsClient({ ably });
Creating a Model
A Model
represents a live, observable data model supported by the database.
To create a model, you need to:
- Define the model's data structure in the frontend application.
- Initialize the model.
- Update the model based on events from the backend.
- Determine how end-users can modify the model.
type Post = {
id: number;
text: string;
comments: string[];
};
async function sync() {
const result = await fetch('/api/post');
return result.json();
}
function merge(state: Post, event: OptimisticEvent | ConfirmedEvent) {
return {
...state,
text: event.data,
}
}
async function updatePost(mutationId: string, content: string) {
const result = await fetch(`/api/post`, {
method: 'PUT',
body: JSON.stringify({ mutationId, content }),
});
return result.json();
}
const model = modelsClient.models.get({
channelName: 'models:posts',
sync: sync,
merge: merge,
})
model.subscribe((err, post) => {
if (err) {
throw err;
}
console.log('post updated:', post);
});
const [confirmation, cancel] = await model.optimistic({
mutationId: 'my-mutation-id',
name: 'updatePost',
data: 'new post text',
})
updatePost('my-mutation-id', 'new post text')
await confirmation;
For more information, see usage docs within this repository.
Documentation and examples
Feedback
The Models SDK is currently in public alpha. We'd love to hear your feedback.