feat: replace waitForRemotePeers() with waku.waitForPeer() method

.size-limit.cjs

@@ -9,7 +9,7 @@ module.exports = [
     path: ["packages/sdk/bundle/index.js", "packages/core/bundle/index.js"],
     import: {
       "packages/sdk/bundle/index.js":
-        "{ createLightNode, waitForRemotePeer, createEncoder, createDecoder, bytesToUtf8, utf8ToBytes, Decoder, Encoder, DecodedMessage, WakuNode  }",
+        "{ createLightNode, createEncoder, createDecoder, bytesToUtf8, utf8ToBytes, Decoder, Encoder, DecodedMessage, WakuNode  }",
     },
   },
   {

packages/interfaces/src/relay.ts

@@ -16,6 +16,7 @@ export interface IRelayAPI {
   readonly pubsubTopics: Set<PubsubTopic>;
   readonly gossipSub: GossipSub;
   start: () => Promise<void>;
+  waitForPeer: () => Promise<void>;
   getMeshPeers: (topic?: TopicStr) => PeerIdStr[];
 }
 

packages/interfaces/src/waku.ts

@@ -10,36 +10,107 @@ import { Protocols } from "./protocols.js";
 import type { IRelay } from "./relay.js";
 import type { IStore } from "./store.js";
 
-export interface Waku {
+export interface IWaku {
   libp2p: Libp2p;
   relay?: IRelay;
   store?: IStore;
   filter?: IFilter;
   lightPush?: ILightPush;
 
+  health: IHealthManager;
   connectionManager: IConnectionManager;
 
+  /**
+   * Dials to the provided peer
+   *
+   * @param {PeerId | MultiaddrInput} peer information to use for dialing
+   * @param {Protocols[]} [protocols] array of Waku protocols to be used for dialing. If no provided - will be derived from mounted protocols.
+   *
+   * @returns {Promise<Stream>} `Promise` that will resolve to a `Stream` to a dialed peer
+   *
+   * @example
+   * ```typescript
+   * await waku.dial(remotePeerId, [Protocols.LightPush]);
+   *
+   * waku.isConnected() === true;
+   * ```
+   */
   dial(peer: PeerId | MultiaddrInput, protocols?: Protocols[]): Promise<Stream>;
 
+  /**
+   * Starts all services and components related to functionality of Waku node.
+   *
+   * @returns {Promise<boolean>} `Promise` that will resolve when started.
+   *
+   * @example
+   * ```typescript
+   * await waku.start();
+   *
+   * waku.isStarted() === true;
+   * ```
+   */
   start(): Promise<void>;
 
+  /**
+   * Stops all recurring processes and services that are needed for functionality of Waku node.
+   *
+   * @returns {Promise<boolean>} `Promise` that resolves when stopped.
+   *
+   * @example
+   * ```typescript
+   * await waku.stop();
+   *
+   * waku.isStarted === false;
+   * ```
+   */
   stop(): Promise<void>;
 
+  /**
+   * Resolves when Waku successfully gains connection to a remote peers that fits provided requirements.
+   * Must be used after attempting to connect to nodes, using {@link IWaku.dial} or
+   * if was bootstrapped by using {@link IPeerExchange} or {@link DnsDiscoveryComponents}.
+   *
+   * @param {Protocols[]} [protocols] Protocols that need to be enabled by remote peers
+   * @param {number} [timeoutMs] Timeout value in milliseconds after which promise rejects
+   *
+   * @returns {Promise<void>} `Promise` that **resolves** if all desired protocols are fulfilled by
+   * at least one remote peer, **rejects** if the timeoutMs is reached
+   * @throws If passing a protocol that is not mounted or Waku node is not started
+   *
+   * @example
+   * ```typescript
+   * try {
+   *  // let's wait for at least one LightPush node and timeout in 1 second
+   *  await waku.waitForPeer([Protocols.LightPush], 1000);
+   * } catch(e) {
+   *  waku.isConnected() === false;
+   *  console.error("Failed to connect due to", e);
+   * }
+   *
+   * waku.isConnected() === true;
+   * ```
+   */
+  waitForPeer(protocols?: Protocols[], timeoutMs?: number): Promise<void>;
+
+  /**
+   * @returns {boolean} `true` if the node was started and `false` otherwise
+   */
   isStarted(): boolean;
 
+  /**
+   * @returns {boolean} `true` if the node has working connection and `false` otherwise
+   */
   isConnected(): boolean;
-
-  health: IHealthManager;
 }
 
-export interface LightNode extends Waku {
+export interface LightNode extends IWaku {
   relay: undefined;
   store: IStore;
   filter: IFilter;
   lightPush: ILightPush;
 }
 
-export interface RelayNode extends Waku {
+export interface RelayNode extends IWaku {
   relay: IRelay;
   store: undefined;
   filter: undefined;

packages/relay/package.json

@@ -58,7 +58,8 @@
     "@waku/utils": "0.0.20",
     "chai": "^4.3.10",
     "debug": "^4.3.4",
-    "fast-check": "^3.19.0"
+    "fast-check": "^3.19.0",
+    "p-event": "^6.0.1"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^25.0.7",

packages/relay/src/relay.ts

@@ -26,6 +26,7 @@ import {
 import { isWireSizeUnderCap, toAsyncIterator } from "@waku/utils";
 import { pushOrInitMapSet } from "@waku/utils";
 import { Logger } from "@waku/utils";
+import { pEvent } from "p-event";
 
 import { RelayCodecs } from "./constants.js";
 import { messageValidator } from "./message_validator.js";
@@ -94,6 +95,22 @@ class Relay implements IRelay {
     this.subscribeToAllTopics();
   }
 
+  /**
+   * Wait for at least one peer with the given protocol to be connected and in the gossipsub
+   * mesh for all pubsubTopics.
+   */
+  public async waitForPeer(): Promise<void> {
+    let peers = this.getMeshPeers();
+    const pubsubTopics = this.pubsubTopics;
+
+    for (const topic of pubsubTopics) {
+      while (peers.length == 0) {
+        await pEvent(this.gossipSub, "gossipsub:heartbeat");
+        peers = this.getMeshPeers(topic);
+      }
+    }
+  }
+
   /**
    * Send Waku message.
    */

packages/sdk/package.json

@@ -70,8 +70,7 @@
     "@waku/proto": "^0.0.8",
     "@waku/utils": "0.0.20",
     "@waku/message-hash": "0.1.16",
-    "libp2p": "^1.8.1",
-    "p-event": "^6.0.1"
+    "libp2p": "^1.8.1"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^25.0.7",

packages/sdk/src/create/create.ts

@@ -1,6 +1,6 @@
 import { type LightNode } from "@waku/interfaces";
 
-import { CreateWakuNodeOptions, WakuNode } from "../waku.js";
+import { CreateWakuNodeOptions, WakuNode } from "../waku/index.js";
 
 import { createLibp2pAndUpdateOptions } from "./libp2p.js";
 

packages/sdk/src/create/libp2p.ts

@@ -21,7 +21,7 @@ import {
   CreateWakuNodeOptions,
   DefaultPingMaxInboundStreams,
   DefaultUserAgent
-} from "../waku.js";
+} from "../waku/index.js";
 
 import { defaultPeerDiscoveries } from "./discovery.js";
 

packages/sdk/src/index.ts

@@ -7,7 +7,7 @@ export {
 
 export { utf8ToBytes, bytesToUtf8 } from "@waku/utils/bytes";
 
-export * from "./waku.js";
+export * from "./waku/index.js";
 
 export {
   createLightNode,
@@ -18,8 +18,6 @@ export { wakuLightPush } from "./protocols/light_push/index.js";
 export { wakuFilter } from "./protocols/filter/index.js";
 export { wakuStore } from "./protocols/store/index.js";
 
-export { waitForRemotePeer } from "./wait_for_remote_peer.js";
-
 export * as waku from "@waku/core";
 export * as utils from "@waku/utils";
 export * from "@waku/interfaces";

packages/sdk/src/waku/index.ts

@@ -0,0 +1,2 @@
+export * from "./waku.js";
+export { waitForRemotePeer } from "./wait_for_remote_peer.js";