refactor: update API with isClosed method and remove requestNetworkConfirmation flag

- Added `isClosed` method to the `Explorer` interface and its implementations (`ElectrumExplorer`, `EsploraExplorer`).
- Removed `requestNetworkConfirmation` flag from `isConnected`, simplifying the API.
- Changed `close` from `async` to synchronous, improving clarity and ensuring immediate execution.
- Fixed reconnection issues by improving error handling during interval pings and ensuring proper cleanup of resources.
- Updated documentation and tests to reflect API changes.
- Bumped package version to 0.4.0 to reflect breaking changes.

Author: landabaso

README.md

@@ -123,7 +123,7 @@ import { EsploraExplorer } from '@bitcoinerlab/explorer';
   const feeEstimates = await explorer.fetchFeeEstimates();
 
   // Close the connection
-  await explorer.close();
+  explorer.close();
 })();
 ```
 

package-lock.json

@@ -2,7 +2,7 @@
   "name": "@bitcoinerlab/explorer",
   "description": "Bitcoin Blockchain Explorer: Client Interface featuring Esplora and Electrum Implementations.",
   "homepage": "https://github.com/bitcoinerlab/explorer",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "author": "Jose-Luis Landabaso",
   "license": "MIT",
   "prettier": "@bitcoinerlab/configs/prettierConfig.json",

package.json

@@ -143,7 +143,12 @@ export class ElectrumExplorer implements Explorer {
    * Implements {@link Explorer#connect}.
    */
   async connect(): Promise<void> {
-    if (await this.isConnected()) throw new Error('Client already connected.');
+    if (this.#pingInterval)
+      throw new Error(
+        'Client was not successfully closed. Prev connection is still pinging.'
+      );
+    if (!this.isClosed())
+      throw new Error('Client previously connected and never closed.');
     this.#client = new ElectrumClient(
       netModule,
       this.#protocol === 'ssl' ? tlsModule : false,
@@ -179,20 +184,22 @@ export class ElectrumExplorer implements Explorer {
       //socket has been init. Here we get an error if electrum server cannot
       //be found in that port, so close the socket
       try {
-        await this.close(); //hide possible socket errors
+        if (!this.isClosed()) this.close();
       } catch (err) {
         console.warn('Error while closing connection:', getErrorMsg(error));
       }
       throw new Error(
         `ElectrumClient failed to connect: ${getErrorMsg(error)}`
       );
     }
+    if (!this.#client) throw new Error('Client should exist at this point');
 
     // Ping every few seconds to keep connection alive.
     // This function will never throw since it cannot be handled
     // In case of connection errors, users will get them on any next function
     // call
     this.#pingInterval = setInterval(async () => {
+      const pingInterval = this.#pingInterval;
       this.#getClientOrThrow();
       let shouldReconnect = false;
       try {
@@ -204,11 +211,15 @@ export class ElectrumExplorer implements Explorer {
           getErrorMsg(error)
         );
       }
-      if (shouldReconnect) {
+      //Dont allow 2 instances of #pingInterval. #pingInterval is set on connection
+      if (shouldReconnect && pingInterval === this.#pingInterval) {
         try {
-          if (await this.isConnected(false)) await this.close(); //hide possible socket errors
+          if (this.isClosed()) throw new Error('Pinging a closed connection');
+          this.close();
           await new Promise(resolve => setTimeout(resolve, 1000));
-          await this.connect();
+          //connect may have been set externally while sleeping, check first
+          if (this.isClosed() && pingInterval === this.#pingInterval)
+            await this.connect();
         } catch (error) {
           console.warn(
             'Error while reconnecting during interval pinging:',
@@ -242,31 +253,32 @@ export class ElectrumExplorer implements Explorer {
    *  Checks server connectivity by sending a ping. Returns `true` if the ping
    * is successful, otherwise `false`.
    */
-  async isConnected(
-    requestNetworkConfirmation: boolean = true
-  ): Promise<boolean> {
-    if (this.#client === undefined) return false;
+  async isConnected(): Promise<boolean> {
+    if (!this.#client) return false;
     else {
-      if (requestNetworkConfirmation) {
-        try {
-          await this.#client.server_ping();
-          return true;
-        } catch {}
-        return false;
-      } else return true;
+      try {
+        await this.#client.server_ping();
+        return true;
+      } catch {}
+      return false;
     }
   }
+  isClosed(): boolean {
+    return !this.#client;
+  }
 
   /**
    * Implements {@link Explorer#close}.
    */
-  async close(): Promise<void> {
+  close(): void {
     if (this.#pingInterval) {
       clearInterval(this.#pingInterval);
       this.#pingInterval = undefined;
     }
     if (!this.#client) console.warn('Client was already closed');
-    else this.#client.close();
+    else {
+      this.#client.close();
+    }
     this.#client = undefined;
   }
 

src/electrum.ts

@@ -26,6 +26,7 @@ function isValidHttpUrl(string: string): boolean {
  * Implements an {@link Explorer} Interface for an Esplora server.
  */
 export class EsploraExplorer implements Explorer {
+  #closed: boolean = true;
   #timeout: number;
   #irrevConfThresh: number;
   #BLOCK_HEIGHT_CACHE_TIME: number = 3; //cache for 3 seconds at most
@@ -64,6 +65,7 @@ export class EsploraExplorer implements Explorer {
     this.#url = url;
     this.#irrevConfThresh = irrevConfThresh;
     this.#maxTxPerScriptPubKey = maxTxPerScriptPubKey;
+    this.#closed = true;
   }
 
   async #esploraFetch(...args: Parameters<typeof fetch>): Promise<Response> {
@@ -123,25 +125,26 @@ export class EsploraExplorer implements Explorer {
   }
 
   async connect() {
+    this.#closed = false;
     return;
   }
   /**
    * Implements {@link Explorer#isConnected}.
    * Checks server connectivity by attempting to fetch the current block height.
    * Returns `true` if successful, otherwise `false`.
    */
-  async isConnected(
-    requestNetworkConfirmation: boolean = true
-  ): Promise<boolean> {
-    if (requestNetworkConfirmation) {
-      try {
-        await this.fetchBlockHeight();
-        return true;
-      } catch {}
-      return false;
-    } else return true;
+  async isConnected(): Promise<boolean> {
+    try {
+      await this.fetchBlockHeight();
+      return true;
+    } catch {}
+    return false;
+  }
+  isClosed(): boolean {
+    return this.#closed;
   }
-  async close() {
+  close() {
+    this.#closed = true;
     return;
   }
 

src/esplora.ts

@@ -40,17 +40,21 @@ export interface Explorer {
    * respond to requests.
    *
    * @async
-   * @param {boolean} [requestNetworkConfirmation=true] When `true`, this checks the network to confirm if the connection is active. When `false`, it only verifies that all required initializations, like calling `connect()` for Electrum clients, have been completed.
    * @returns {Promise<boolean>} Promise resolving to `true` if the server is
    * reachable and responding; otherwise, `false`.
    */
-  isConnected(requestNetworkConfirmation?: boolean): Promise<boolean>;
+  isConnected(): Promise<boolean>;
+
+  /**
+   * Returns true if connect has never been called
+   * or if close() was called after a connect().
+   */
+  isClosed(): boolean;
 
   /**
    * Close the connection.
-   * @async
    */
-  close(): Promise<void>;
+  close(): void;
 
   /**
    * Get the balance of an address and find out whether the address ever

src/interface.ts

@@ -221,8 +221,8 @@ for (const regtestExplorer of regtestExplorers) {
         ) //Push a problematic tx that has "Missing inputs"
       ).rejects.toThrow(/bad-txns-inputs-missingorspent/);
     });
-    test('close', async () => {
-      await explorer.close();
+    test('close', () => {
+      explorer.close();
     });
   });
 }
@@ -300,8 +300,8 @@ describe('Explorer: Tests with public servers', () => {
       const blockStatus2 = await explorer.fetchBlockStatus(847612);
       expect(blockStatus2).toBe(blockStatus); // Checks reference equality
     }, 30000);
-    test(`close ${explorerName}`, async () => {
-      await explorer.close();
+    test(`close ${explorerName}`, () => {
+      explorer.close();
       //await new Promise(r => setTimeout(r, 9000));
     }, 10000);
   }