{"id":20058814,"url":"https://github.com/ably-labs/models","last_synced_at":"2025-05-05T15:30:23.335Z","repository":{"id":208817377,"uuid":"647696774","full_name":"ably-labs/models","owner":"ably-labs","description":"The Models SDK enables you to implement live, observable data models in your application. It works with Ably's Database Connector and helps merge updates with the existing state and supports optimistic updates to ensure a snappy interface.","archived":false,"fork":false,"pushed_at":"2024-09-03T15:21:45.000Z","size":3050,"stargazers_count":6,"open_issues_count":10,"forks_count":2,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-11-02T20:33:44.212Z","etag":null,"topics":["frontend-web","pubsub","realtime","realtime-database","realtime-synchronization","websockets"],"latest_commit_sha":null,"homepage":"https://models-blush.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ably-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-31T10:31:01.000Z","updated_at":"2024-08-22T14:51:12.000Z","dependencies_parsed_at":"2024-01-08T22:23:13.621Z","dependency_job_id":"7f83453a-6180-4757-a34f-72f70d663a10","html_url":"https://github.com/ably-labs/models","commit_stats":{"total_commits":434,"total_committers":11,"mean_commits":39.45454545454545,"dds":"0.35253456221198154","last_synced_commit":"d81b8d05de445145c8ce09088deac825f667b636"},"previous_names":["ably-labs/models"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably-labs%2Fmodels","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably-labs%2Fmodels/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably-labs%2Fmodels/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably-labs%2Fmodels/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ably-labs","download_url":"https://codeload.github.com/ably-labs/models/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224427857,"owners_count":17309372,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["frontend-web","pubsub","realtime","realtime-database","realtime-synchronization","websockets"],"created_at":"2024-11-13T13:04:14.729Z","updated_at":"2024-11-13T13:04:15.200Z","avatar_url":"https://github.com/ably-labs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ably Models SDK\n\n\u003cp align=\"left\"\u003e\n  \u003ca href=\"\"\u003e\n    \u003cimg src=\"https://badgen.net/badge/development-status/alpha/yellow?icon=github\" alt=\"Development status\"   /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"\"\u003e\n    \u003cimg src=\"https://github.com/ably-labs/models/actions/workflows/dev-ci.yml/badge.svg?branch=main\" alt=\"CI status\"   /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n- [Ably Models SDK](#ably-models-sdk)\n  - [Overview](#overview)\n  - [Development Status](#development-status)\n  - [Quickstart](#quickstart)\n    - [Prerequisites](#prerequisites)\n    - [Installation and authentication](#installation-and-authentication)\n    - [Instantiation](#instantiation)\n    - [Creating a Model](#creating-a-model)\n  - [Documentation and examples](#documentation-and-examples)\n  - [Feedback](#feedback)\n\n---\n\n## Overview\n\nThe Ably Models SDK is a key component of the [LiveSync](https://ably.com/docs/products/livesync) product that lets you stream realtime updates from your database at scale to frontend clients.\n\n![LiveSync Diagram](/docs/images/what-is-livesync.png \"LiveSync Diagram\")\n\nThe 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.\n\nThe Database Connector and Ably Channels are the other two components of LiveSync that help publish changes from your database to frontend clients.\n\nA 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. \n\n![Models SDK Diagram](/docs/images/models-diagram.png \"Models SDK Diagram\")\n\n\nWhen creating a new Model using the Models SDK you provide two functions to the Model a `sync()` function and a `merge()` function:\n- The `sync(`) function is used by the SDK to retrieve the current state of the data model from your backend.\n- 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.\n\nYou 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.\n\nThe 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.\n\n\n## Development Status\n\nLiveSync, and the Models SDK, is in public alpha so that you can explore its capabilities. Your [feedback](https://docs.google.com/forms/d/e/1FAIpQLSd00n1uxgXWPGvMjKwMVL1UDhFKMeh3bSrP52j9AfXifoU-Pg/viewform) 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.\n\n## Quickstart\n\n### Prerequisites\n\nTo begin, you will need the following:\n\n* An Ably account. You can [sign up](https://ably.com/signup) for free.\n* An Ably API key. You can create API keys in an app within your [Ably account](https://ably.com/dashboard).\n  * The API key needs `subscribe` [capabilities](https://ably.com/docs/auth/capabilities).\n\n### Installation and authentication\n\nInstall the Ably JavaScript SDK and the Realtime Data Models SDK:\n\n```sh\nnpm install ably @ably-labs/models\n```\nThough you can test your installation and authentication with [basic authentication](https://ably.com/docs/auth/basic), we strongly recommend [token authentication](https://ably.com/docs/auth/token) for in production environments.\n\n### Instantiation\n\nTo instantiate the Realtime Data Models SDK, create an [Ably client](https://ably.com/docs/getting-started/setup) and pass it into the ModelsClient constructor:\n\n```typescript\nimport ModelsClient from '@ably-labs/models';\nimport { Realtime } from 'ably';\n\nconst ably = new Realtime({ key: 'YOUR_ABLY_API_KEY' });\nconst modelsClient = new ModelsClient({ ably });\n```\n\n### Creating a Model\n\nA `Model` represents a live, observable data model supported by the database.\n\nTo create a model, you need to:\n\n1. Define the model's data structure in the frontend application.\n2. Initialize the model.\n3. Update the model based on events from the backend.\n4. Determine how end-users can modify the model.\n\n```typescript\n// this is the type for our model's data as represented in the frontend application\ntype Post = {\n  id: number;\n  text: string;\n  comments: string[];\n};\n\n// a function used by the model to initialise with the correct data from your backend\nasync function sync() {\n  const result = await fetch('/api/post');\n  return result.json(); // e.g. { sequenceId: 1, data: { ... } }\n}\n\n// a function used by the model to merge a change event that is received and the existing model state\nfunction merge(state: Post, event: OptimisticEvent | ConfirmedEvent) {\n  return {\n    ...state,\n    text: event.data, // replace the previous post text field with the new value\n  }\n}\n\n// a function that you might use to mutate the model data in your backend\nasync function updatePost(mutationId: string, content: string) {\n  const result = await fetch(`/api/post`, {\n    method: 'PUT',\n    body: JSON.stringify({ mutationId, content }),\n  });\n  return result.json();\n}\n\n// create a new model instance called 'post' by passing the sync and merge functions\nconst model = modelsClient.models.get({\n  channelName: 'models:posts',\n  sync: sync,\n  merge: merge,\n})\n\n// subscribe to live changes to the model data!\nmodel.subscribe((err, post) =\u003e {\n  if (err) {\n    throw err;\n  }\n  console.log('post updated:', post);\n});\n\n\n// apply an optimistic update to the model\n// confirmation is a promise that resolves when the optimistic update is confirmed by the backend.\n// cancel is a function that can be used to cancel and rollback the optimistic update.\nconst [confirmation, cancel] = await model.optimistic({\n    mutationId: 'my-mutation-id',\n    name: 'updatePost',\n    data: 'new post text',\n})\n\n// call your backend to apply the actual change\nupdatePost('my-mutation-id', 'new post text')\n\n// wait for confirmation of the change from the backend\nawait confirmation;\n```\n\nFor more information, see [usage docs](./docs/usage.md) within this repository.\n\n## Documentation and examples\n\n* Read the [docs on Ably website](https://ably.com/docs/products/livesync).\n* Browse the [API Reference](https://sdk.ably.com/builds/ably-labs/models/main/typedoc/).\n* Explore the [examples](/examples).\n\n## Feedback\n\nThe Models SDK is currently in public alpha. [We'd love to hear your feedback](https://forms.gle/1XrVbYkhxFvUPBDd7).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fably-labs%2Fmodels","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fably-labs%2Fmodels","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fably-labs%2Fmodels/lists"}