Getting Started

@skyware/firehose is a utility library for consuming data from an AT Protocol Relay.

Setup

import { class FirehoseFirehose } from "@skyware/firehose";

const const firehose: Firehosefirehose = new new Firehose(options?: FirehoseOptions): Firehose
Creates a new Firehose instance.
@paramoptions Optional configuration.
Firehose
();

The Firehose class takes two optional parameters.

  • The first is the URL of the Relay to connect to. This defaults to wss://bsky.network, the Relay run by Bluesky.
  • The second is an options object, which lets you provide:
  • cursor: The cursor to start listening from. A cursor is included in every event emitted by the Relay. If you don’t provide a cursor, the Firehose will start listening from the most recent event.
  • setCursorInterval: By default, the Firehose class will keep track of the latest cursor under thr cursor property every 5 seconds. This allows you to save the cursor or resume from that point in case of an error. You can change this interval by providing a number of milliseconds.

Handling events

const firehose: Firehosefirehose.Firehose.on(event: "commit", listener: (message: ParsedCommit) => void): Firehose (+11 overloads)
Represents a commit to a user's repository.
@sincev0.1.101@parameventName The name of the event.@paramlistener The callback function
on
("commit", (message: ParsedCommitmessage) => {
for (const const op: RepoOpop of message: ParsedCommitmessage.ParsedCommit.ops: RepoOp[]
List of repo mutation operations in this commit (eg, records created, updated, or deleted).
ops
) {
const const uri: stringuri = "at://" + message: ParsedCommitmessage.ParsedCommit.repo: string
The repo this event comes from.
repo
+ "/" + const op: RepoOpop.path: string
The record's path in the repository.
path
;
var console: Console
The console module provides a simple debugging console that is similar to the JavaScript console mechanism provided by web browsers. The module exports two specific components: * A Console class with methods such as console.log(), console.error() andconsole.warn() that can be used to write to any Node.js stream. * A global console instance configured to write to process.stdout and process.stderr. The global console can be used without callingrequire('console'). _**Warning**_: The global console object's methods are neither consistently synchronous like the browser APIs they resemble, nor are they consistently asynchronous like all other Node.js streams. See the note on process I/O for more information. Example using the global console: console.log('hello world'); // Prints: hello world, to stdout console.log('hello %s', 'world'); // Prints: hello world, to stdout console.error(new Error('Whoops, something bad happened')); // Prints error message and stack trace to stderr: // Error: Whoops, something bad happened // at [eval]:5:15 // at Script.runInThisContext (node:vm:132:18) // at Object.runInThisContext (node:vm:309:38) // at node:internal/process/execution:77:19 // at [eval]-wrapper:6:22 // at evalScript (node:internal/process/execution:76:60) // at node:internal/main/eval_string:23:3 const name = 'Will Robinson'; console.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to stderr Example using the Console class: const out = getStreamSomehow(); const err = getStreamSomehow(); const myConsole = new console.Console(out, err); myConsole.log('hello world'); // Prints: hello world, to out myConsole.log('hello %s', 'world'); // Prints: hello world, to out myConsole.error(new Error('Whoops, something bad happened')); // Prints: [Error: Whoops, something bad happened], to err const name = 'Will Robinson'; myConsole.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to err
@seesource
console
.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)
Prints to stdout with newline. Multiple arguments can be passed, with the first used as the primary message and all additional used as substitution values similar to `printf(3)` (the arguments are all passed to util.format()). const count = 5; console.log('count: %d', count); // Prints: count: 5, to stdout console.log('count:', count); // Prints: count: 5, to stdout See util.format() for more information.
@sincev0.1.100
log
("URI:", const uri: stringuri);
} });

A Relay listens for changes to user repositories and emits events when changes occur. You can listen for these events by calling the on method with a callback. Full documentation on the data you will receive with each event can be found in the Firehose#on method documentation.

The most common event you will receive is a commit event, which represents a commit to a user’s repository, similar to a Git commit.

A commit may contain one or more operations, representing changes to the repository. Each operation contains an action and a path. The action can be one of create, update, or delete. The path is the path to the record affected (e.g. app.bsky.feed.post/3jvz2442yt32g).

If the operation is create or update, it will also contain the following properties:

  • cid: The CID of the created or updated record.
  • record: The record itself.

Event Reference

The Firehose class may emit the following events:

Relay events

EventDescription
commitRepresents a commit to a user’s repository.
identityRepresents a change to an account’s identity. Could be an updated handle, signing key, or PDS hosting endpoint.
handleRepresents an update of an account’s handle, or transition to/from invalid state (may be deprecated in favor of identity).
tombstoneIndicates that an account has been deleted (may be deprecated in favor of identity or a future account event).
infoAn informational message from the relay.
unknownEmitted when an unknown event is emitted by the relay.

System events

EventDescription
openEmitted when the websocket connection is opened.
closeEmitted when the websocket connection is closed.
errorEmitted when an error occurs while handling a message.
websocketErrorEmitted when an error occurs with the websocket connection.