> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript Live Objects & Collections

> Observe Social+ TypeScript SDK objects and collections with callbacks, pagination helpers, and real-time topic subscriptions.

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.

<CodeGroup>
  ```typescript TypeScript theme={null}
  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?.();
  }
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```typescript TypeScript theme={null}
  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();
  }
  ```
</CodeGroup>

## 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()`.

## Related Topics

<CardGroup cols={2}>
  <Card title="Post Retrieval" icon="newspaper" href="/social-plus-sdk/social/content-management/posts/retrieval/get-post">
    See post-specific live object and collection usage.
  </Card>

  <Card title="TypeScript Real-time Events" icon="radio-tower" href="/social-plus-sdk/core-concepts/realtime-communication/realtime-events/social-realtime-events">
    Subscribe to social topics for cross-device updates.
  </Card>
</CardGroup>