@synonymdev/pubky
    Preparing search index...

    Class EventStreamBuilder

    Builder for creating an event stream subscription.

    Construct via Pubky.eventStreamForUser() or Pubky.eventStreamFor(). Configuration methods consume this builder unless documented otherwise.

    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 maxEventBytes 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. Updates this builder and returns a copy for chaining. Rejected input leaves this builder unchanged.

      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

    • Set a client-side byte limit for SSE payloads. Unbounded by default. Limits accumulated data (including newlines joining data fields), each event name, and each ID separately in historical and live streams. Comments, unknown fields and framing bytes are excluded. There is no total block or stream byte limit. Overflow cancels the response and errors the ReadableStream. Updates this builder and returns a copy for chaining. Rejected input leaves this builder unchanged.

      Parameters

      • limit: number

        Integer in 1..=4294967295.

      Returns EventStreamBuilder

      If the limit is not a positive 32-bit integer.

    • 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