TypeScript Live Objects & Collections

The TypeScript SDK exposes live objects and live collections through repository callbacks. A live object callback receives one object snapshot. A live collection callback receives a list snapshot plus pagination helpers when the query supports paging. Repository observers watch SDK cache state. For cross-device real-time updates, subscribe to the topic that matches the object or collection scope, then clean up both the repository observer and the topic subscription.

Platform Surface

Surface	Public shape	Notes
Live object	`Amity.LiveObject<T>`	Callback payload includes `data`, `loading`, `error`, and optional `origin`.
Live collection	`Amity.LiveCollection<T>`	Extends the live-object shape with `onNextPage`, `hasNextPage`, `onPrevPage`, and `hasPrevPage` where available.
Observer cleanup	`Amity.Unsubscriber`	Repository live methods return an unsubscribe function.
Real-time topic cleanup	`Amity.Unsubscriber`	`subscribeTopic()` returns a separate unsubscribe function.
Collection config	`Amity.LiveCollectionConfig`	Supports query policies except `no_fetch`.

Parameters

Parameter	Used by	Description
`postId` or another entity ID	Live object methods	ID of the object to observe, such as a post, message, channel, community, user, poll, room, or stream.
`params.targetType` / `params.targetId`	Collection queries such as `PostRepository.getPosts()`	Scope for the list. For posts, `targetType` is commonly `user` or `community`.
`limit`	Collection queries	Optional page size for the query.
`callback`	Object and collection methods	Receives each live snapshot. Handle `loading` and `error` before rendering data.
`onNextPage` / `hasNextPage`	Live collections	Use when the UI asks for the next page. Do not call `onNextPage` repeatedly without checking `hasNextPage`.
`subscribeTopic(topic, callback?)`	Real-time updates	Subscribes the active client to a topic such as `getPostTopic(post)` or `getCommunityTopic(community, SubscriptionLevels.POST)`.

Observe A Live Object

This example observes one post and subscribes to the post topic after the first post snapshot is available.

import { PostRepository, getPostTopic, subscribeTopic } from "@amityco/ts-sdk";

let unsubscribePostTopic: Amity.Unsubscriber | undefined;

const unsubscribePost = PostRepository.getPost(postId, snapshot => {
  if (snapshot.loading) {
    showLoading();
  }

  if (snapshot.error) {
    handleError(snapshot.error);
    return;
  }

  const currentPost = snapshot.data;
  renderResults(currentPost);

  if (!unsubscribePostTopic) {
    unsubscribePostTopic = subscribeTopic(getPostTopic(currentPost), error => {
      if (error) handleError(error);
    });
  }
});

function stopObservingPost() {
  unsubscribePost();
  unsubscribePostTopic?.();
}

Observe A Live Collection

Use the collection callback to render the latest list. Keep the next-page function and call it only when the UI requests more data.

import {
  PostRepository,
  SubscriptionLevels,
  getCommunityTopic,
  subscribeTopic,
} from "@amityco/ts-sdk";

let hasMorePosts = false;
let loadNextPostsPage: (() => void) | undefined;

const unsubscribePostsTopic = subscribeTopic(
  getCommunityTopic(community, SubscriptionLevels.POST),
  error => {
    if (error) handleError(error);
  }
);

const unsubscribePosts = PostRepository.getPosts(
  {
    targetType: "community",
    targetId: communityId,
    limit: 20,
    sortBy: "lastCreated",
    includeDeleted: false,
  },
  collection => {
    if (collection.loading) {
      showLoading();
    }

    if (collection.error) {
      handleError(collection.error);
      return;
    }

    renderResults(collection.data);
    hasMorePosts = collection.hasNextPage ?? false;
    loadNextPostsPage = collection.onNextPage;
  }
);

function loadMorePosts() {
  if (hasMorePosts) {
    loadNextPostsPage?.();
  }
}

function stopObservingPosts() {
  unsubscribePosts();
  unsubscribePostsTopic();
}

Notes

getPost(), getMessage(), getChannel(), getCommunity(), getUser(), getPoll(), getRoom(), and similar singular methods follow the same live-object callback pattern.
Query methods such as getPosts(), getComments(), getMessages(), getMembers(), getReactions(), getRooms(), and getStreams() follow the live-collection callback pattern.
The callback can emit local/cache data before server data. Use loading, error, and origin if your UI needs to distinguish phases.
Keep topic subscriptions as narrow as possible. A post-detail screen should subscribe to the post topic; a community feed screen should subscribe to the community post topic.
Always dispose the observer returned by the repository and any topic unsubscribe functions returned by subscribeTopic().

Post Retrieval

See post-specific live object and collection usage.

TypeScript Real-time Events

Subscribe to social topics for cross-device updates.

Powered by

Getting Started

Fundamentals

Social

Chat

Video

Release Notes

Migration Guides

Support

TypeScript Live Objects & Collections

Platform Surface

Parameters

Observe A Live Object

Observe A Live Collection

Notes

Post Retrieval

TypeScript Real-time Events

​Platform Surface

​Parameters

​Observe A Live Object

​Observe A Live Collection

​Notes

​Related Topics

Post Retrieval

TypeScript Real-time Events

Platform Surface

Parameters

Observe A Live Object

Observe A Live Collection

Notes

Related Topics