Getting Started
@skyware/firehose
is a utility library for consuming data from an AT Protocol Relay.
Setup
import { class Firehose
Firehose } from "@skyware/firehose";
const const firehose: Firehose
firehose = new new Firehose(options?: FirehoseOptions): Firehose
Creates a new Firehose instance.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 thrcursor
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: Firehose
firehose.Firehose.on(event: "commit", listener: (message: ParsedCommit) => void): Firehose (+11 overloads)
Represents a commit to a user's repository.on("commit", (message: ParsedCommit
message) => {
for (const const op: RepoOp
op of message: ParsedCommit
message.ParsedCommit.ops: RepoOp[]
List of repo mutation operations in this commit (eg, records created, updated, or deleted).ops) {
const const uri: string
uri = "at://" + message: ParsedCommit
message.ParsedCommit.repo: string
The repo this event comes from.repo + "/" + const op: RepoOp
op.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
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.log("URI:", const uri: string
uri);
}
});
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
Event | Description |
---|---|
commit | Represents a commit to a user’s repository. |
identity | Represents a change to an account’s identity. Could be an updated handle, signing key, or PDS hosting endpoint. |
handle | Represents an update of an account’s handle, or transition to/from invalid state (may be deprecated in favor of identity ). |
tombstone | Indicates that an account has been deleted (may be deprecated in favor of identity or a future account event). |
info | An informational message from the relay. |
unknown | Emitted when an unknown event is emitted by the relay. |
System events
Event | Description |
---|---|
open | Emitted when the websocket connection is opened. |
close | Emitted when the websocket connection is closed. |
error | Emitted when an error occurs while handling a message. |
websocketError | Emitted when an error occurs with the websocket connection. |