@synonymdev/pubky
    Preparing search index...

    Class EventStreamBuilder

    Builder for creating an event stream subscription.

    Construct via Pubky.eventStreamForUser() or Pubky.eventStreamFor().

    const stream = await pubky.eventStreamForUser(userPubkey, null)
      .live()
      .limit(100)
      .path("/pub/")
      .subscribe();

    for await (const event of stream) {
      console.log(event.eventType, event.resource.path);
    }

    // Private events: attach a session and request a `/priv/...` path.
    const stream = await pubky.eventStreamForUser(userPubkey, null)
      .session(session)
      .path("/priv/app/")
      .subscribe();
    Index
    [dispose] addUsers free limit live path reverse session subscribe

    • Returns void

    • Add multiple users to the event stream subscription at once.

      Each user can have an independent cursor position. If a user already exists, their cursor value is overwritten.

      Parameters

      • users: any[]

        Array of [z32PublicKey, cursor] tuples

      Returns EventStreamBuilder

      • Builder for chaining
      • If total users would exceed 50 or if any cursor/pubkey is invalid
      const users: [string, string | null][] = [
        [user1.z32(), null],
        [user2.z32(), "100"],
      ];
      const stream = await pubky.eventStreamFor(homeserver)
        .addUsers(users)
        .live()
        .subscribe();

    • Returns void

    • Set maximum number of events to receive before closing the connection.

      If omitted:

      • With live=false: sends all historical events, then closes
      • With live=true: sends all historical events, then enters live mode (infinite stream)

      Parameters

      • limit: number

        Maximum number of events (1-65535)

      Returns EventStreamBuilder

      • Builder for chaining

    • Enable live streaming mode.

      When called, the stream will:

      1. First deliver all historical events (oldest first)
      2. Then remain open to stream new events as they occur in real-time

      Without this flag (default): Stream only delivers historical events and closes.

      Note: Cannot be combined with reverse().

      To stop a live stream, use the reader's cancel() method:

      const stream = await pubky.eventStreamForUser(user, null).live().subscribe();
      const reader = stream.getReader();

      while (true) {
        const { done, value } = await reader.read();
        if (shouldStop) {
          await reader.cancel(); // Closes the connection
          break;
        }
      }

      Returns EventStreamBuilder

      • Builder for chaining

    • Filter events by path. Call once per path to receive the union of several scopes (e.g. /pub/ plus a private /priv/app/).

      Format: a path WITHOUT the pubky:// scheme or user pubkey. A trailing slash matches a directory and all its descendants (/pub/files/); no trailing slash matches an exact file (/pub/notes.txt).

      Private (/priv/...) paths require a session attached via session(); without one the homeserver rejects the subscription with 401.

      Parameters

      • path: string

        Path filter (repeatable)

      Returns EventStreamBuilder

      • Builder for chaining

    • Return events in reverse chronological order (newest first).

      When called, events are delivered from newest to oldest, then the stream closes.

      Without this flag (default): Events are delivered oldest first.

      Note: Cannot be combined with live().

      Returns EventStreamBuilder

      • Builder for chaining

    • Authenticate the subscription with a user Session.

      Required to receive private (/priv/...) events: the session credential (grant or cookie) is attached so the homeserver can authorize each private path() against the session's read capabilities. Public subscriptions don't need this.

      Parameters

      • session: Session

        The authenticated session

      Returns EventStreamBuilder

      • Builder for chaining

    • Subscribe to the event stream.

      This performs the following steps:

      1. Resolves the user's homeserver via DHT/PKDNS
      2. Constructs the /events-stream URL with query parameters
      3. Makes the HTTP request
      4. Returns a Web ReadableStream of parsed events

      Returns Promise<ReadableStream<any>>

      • A Web ReadableStream that yields Event objects
      • { name: "RequestError" } if the homeserver cannot be resolved
      • { name: "ValidationError" } if live=true and reverse=true (invalid combination)
      • Propagates HTTP request errors
      const stream = await builder.subscribe();
      for await (const event of stream) {
        console.log(`${event.eventType}: ${event.resource.path}`);
      }

    Settings

    On This Page
    Methods