From ae717a1a4ad19966e985961bd4ba28ceb49cf0a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=8D=C3=B1igo=20Ar=C3=A9jula=20A=C3=ADsa?=
 <arejula27@gmail.com>
Date: Sat, 26 Nov 2022 03:20:22 +0100
Subject: [PATCH] Documentation pool.js (#30)

---
 pool.js | 37 +++++++++++++++++++++++++++++++------
 1 file changed, 31 insertions(+), 6 deletions(-)

diff --git a/pool.js b/pool.js
index e1e7207..d28e0ae 100644
--- a/pool.js
+++ b/pool.js
@@ -14,6 +14,9 @@ export function relayPool() {
     // been published -- or at least attempted to be published -- to all relays
     wait: false
   }
+  
+  //map with all the relays where the url is the id
+  //Map<string,{relay:Relay,policy:RelayPolicy>
   const relays = {}
   const noticeCallbacks = []
 
@@ -26,12 +29,17 @@ export function relayPool() {
 
   const activeSubscriptions = {}
 
+  //sub creates a Subscription object {sub:Function, unsub:Function, addRelay:Function,removeRelay :Function }
   const sub = ({cb, filter, beforeSend}, id, cbEose) => {
+    
+    //check if it has an id, if not assign one
     if (!id) id = Math.random().toString().slice(2)
-
     const subControllers = Object.fromEntries(
+      //Convert the map<string,Relay> to a Relay[]
       Object.values(relays)
+         //takes only relays that can be read
         .filter(({policy}) => policy.read)
+         //iterate all the rellies and create the array [url:string,sub:SubscriptionCallback] 
         .map(({relay}) => [
           relay.url,
           relay.sub({cb: event => cb(event, relay.url), filter, beforeSend}, id,
@@ -39,26 +47,33 @@ export function relayPool() {
         ])
     )
 
-    const activeCallback = cb
-    const activeFilters = filter
-    const activeBeforeSend = beforeSend
+    const activeCallback = cb //assign callback for the suscription
+    const activeFilters = filter //assigng filter for the suscrition
+    const activeBeforeSend = beforeSend //assign before send fucntion
 
+    //Unsub deletes itself 
     const unsub = () => {
+      //iterate the map of subControllers and call the unsub function of it relays 
       Object.values(subControllers).forEach(sub => sub.unsub())
-      delete activeSubscriptions[id]
+      delete activeSubscriptions[id] 
     }
+    
+  
     const sub = ({
       cb = activeCallback,
       filter = activeFilters,
       beforeSend = activeBeforeSend
     }) => {
+      //Iterates the subControllers and add them the atributes of our Subscription (callback, filter,etc.)
       Object.entries(subControllers).map(([relayURL, sub]) => [
         relayURL,
         sub.sub({cb: event => cb(event, relayURL), filter, beforeSend}, id,
           () => cbEose(relayURL))
       ])
+      //returns the current suscripcion
       return activeSubscriptions[id]
     }
+    //addRelay adds a relay to the subControllers map so the current subscription can use it
     const addRelay = relay => {
       subControllers[relay.url] = relay.sub(
         {cb: event => cb(event, relay.url), filter, beforeSend},
@@ -66,6 +81,7 @@ export function relayPool() {
       )
       return activeSubscriptions[id]
     }
+    //removeRelay deletes a relay from the subControllers map, it also handles the unsubscription from the relay
     const removeRelay = relayURL => {
       if (relayURL in subControllers) {
         subControllers[relayURL].unsub()
@@ -74,6 +90,7 @@ export function relayPool() {
       return activeSubscriptions[id]
     }
 
+    //add the object created to activeSubscriptions map
     activeSubscriptions[id] = {
       sub,
       unsub,
@@ -96,6 +113,7 @@ export function relayPool() {
     setPolicy(key, value) {
       poolPolicy[key] = value
     },
+    //addRelay adds a relay to the pool and to all its subscriptions
     addRelay(url, policy = {read: true, write: true}) {
       let relayURL = normalizeRelayURL(url)
       if (relayURL in relays) return
@@ -113,6 +131,7 @@ export function relayPool() {
 
       return relay
     },
+    //remove relay deletes the relay from the pool and from all its subscriptions
     removeRelay(url) {
       let relayURL = normalizeRelayURL(url)
       let data = relays[relayURL]
@@ -132,9 +151,12 @@ export function relayPool() {
       let index = noticeCallbacks.indexOf(cb)
       if (index !== -1) noticeCallbacks.splice(index, 1)
     },
+    
+    //publish send a event to the relays 
     async publish(event, statusCallback) {
       event.id = getEventHash(event)
-
+      
+      //if the event is not signed then sign it 
       if (!event.sig) {
         event.tags = event.tags || []
 
@@ -159,6 +181,7 @@ export function relayPool() {
         }
       }
 
+      //get the writable relays
       let writeable = Object.values(relays)
         .filter(({policy}) => policy.write)
         .sort(() => Math.random() - 0.5) // random
@@ -169,6 +192,7 @@ export function relayPool() {
 
       let successes = 0
 
+      //if the pool policy set to want until event send
       if (poolPolicy.wait) {
         for (let i = 0; i < writeable.length; i++) {
           let {relay} = writeable[i]
@@ -193,6 +217,7 @@ export function relayPool() {
             /***/
           }
         }
+        //if the pool policy dont  want to wait  until event send
       } else {
         writeable.forEach(async ({relay}) => {
           let callback = statusCallback