Skip to main content
Module

x/earthstar/mod.browser.ts>IQueryFollower

A specification and Javascript library for building online tools you can truly call your own.
earthstar-project/earthstar
Go to Latest
interface IQueryFollower
Re-export
import { type IQueryFollower } from "https://deno.land/x/earthstar@v9.3.3/mod.browser.ts";

Subscribe to the ongoing results of a query, optionally including old existing docs.

const myFollower = new QueryFollower(replica, myQuery);
myFollower.bus.on(async (event: LiveQueryEvent) => {
   if (event.kind === 'existing' || event.kind === 'success') {
       doSomething(event.doc)
   }
});

await qf.hatch();

Properties

replica: IReplica
query: Query

The query being followed. Has some limitations:

  • historyMode must be all
  • orderBy must be localIndex ASC
  • limit can NOT be set.
bus: Simplebus<LiveQueryEvent>

Use this to subcribe to events with a callback, which will be called blockingly (one event at a time, one callback at a time).

For now it's tricky to close a query follower from inside its own event handler; you have to do it using setTimeout or you'll deadlock on the bus's lock.

qf.bus.on(await (event) => {
  setTimeout(() => qf.close(), 0);
});

(because you can't send an event from inside an event handler)

Methods

state(): QueryFollowerState

Returns the follower's state, which can be in two modes:

  1. catching up with the backlog
  2. caught up; processing new events as they happen. When the query follower is in catching-up mode, it runs independently on its own schedule. When it's in live mode, it processes each doc as it's written, blockingly, which means it provides backpressure all the way back up to whatever is trying to ingest() docs into the replica. There is not currently an easy way to know when a query follower has caught up and switched to live mode, except to listen for the 'idle' event on its bus.
hatch(): Promise<void>

Begins the process of catching up with existing documents (if needed), then switches to live mode.

close(): Promise<void>

Permanently shut down the QueryFollower, unhooking from the replica and stopping the processing of events. Automatically called when the followed replica closes.