Consume

tip

Just getting started? Check out our Getting Connected Guide to get your client setup This document assumes that you've already followed our installation guide

Let's explore how use Ceramic to read messages from a stream. Nodes in the Ceramic Network subscribe to data by expressing an interest in a given data model. This interest is broadcast to the node's peers in the network, who will then initiate periodic synchronization of all data conforming to that model via Recon, a protocol tailor-made for the efficient synchronization of large sets of events.

Consuming events

First, we'll learn how to register an interest. Then we'll learn how to read events matching our interests. Finally, we'll learn about some extra methods to fetch specific events from your ceramic-one node.

registerInterestModel

This method allows end users to register interest in a specific data model within the Ceramic network. The model's identifier is, itself, the ID of a stream that defines its schema.

import { CeramicClient, EventsFeedParams } from "@ceramic-sdk/http-client";

const ceramic = new CeramicClient({ url: "http://localhost:5101" });

// My model stream ID
const modelId = "kjzl6hvfrbw6c5i55ks5m4hhyuh0jylw4g7x0asndu97i7luts4dfzvm35oev65";

// Listen to all events written to instances of this modela
await ceramic.registerInterestModel(modelId);

Upon success, the function won't return anything, but it will throw if there's an issue. You're now ready to read events from streams tied to this schema!

getEventsFeed

This method allows users to poll for new events that match their interests. It follows a typical pagination screen, in which users may specify limit, the maxinum number of results to return in a given query, and resumeAt an opaque token that the ceramic-one node can use to determine where the user left off in their last read.

Prepare your request parameters

Let's assume I want to read 50 events matching my interests. Both of these parameters are optional, but we'll define them to illustrate their purpose. If no limit is defined, the SDK will retrieve all new events from the resume token.

const params: EventsFeedParams = {
  limit: 50,
  resumeAt: "0", // The resumeToken returned from the last call to `getEventsFeed`
};

Get a batch of events

const events = await ceramic.getEventsFeed(params);

If there is an issue, getEventsFeed will throw. Otherwise, you'll get an object shaped like this:

type EventsFeed = {
  events: {
    id: string;
    data?: string;
  }[];
  resumeToken: string;
};

Getting individual events

Ceramic also offers a handful of simple APIs to fetch individual events from your ceramic-one node.

getEvent

This is the most straightforward of the event fetching methods. It returns an event of the form:

type Event = {
  id: string;
  data?: string;
};

To fetch an event by its id, we use getEvent:

const eventId = events.events[0].id; // The ID of the event we want to fetch
const event = await ceramic.getEvent(eventId);

There are also a small collection of simple helper functions to extract specific parts of an event.

getEventData

Extract the data payload from an event.

const data = await ceramic.getEventData(eventId);

This is equivalent to:

ceramic.getEvent(eventId).then((event) => event.data);

getEventCAR

Extract the data payload from an event and parse it as a CAR file.

const data = await ceramic.getEventCAR(eventId);

data will be the parsed payload of the event.

getEventType

This method is useful for cases where you know the schema of the payload. To use it, you must have the codeco package and your codec handy.

npm install --save codeco

Then, you can use it like this:

import { Decoder } from "codeco";

type MyPayload = /* ... */;
const decoder: Decoder<unknown, MyPayload> = /* ... */;

const data: MyPayload = await ceramic.getEventType(decoder, eventId);