@agoric/network 0.1.1-dev-7ffae88.0 → 0.1.1-orchestration-dev-096c4e8.0

package/src/types.js

@@ -1,3 +1,10 @@
+// @ts-check
+
+/**
+ * @template T
+ * @typedef {Promise<T | import('@agoric/vow').Vow<T>>} PromiseVow
+ */
+
 /**
  * @typedef {string | Buffer | ArrayBuffer} Data
  *
@@ -11,12 +18,12 @@
 
 /**
  * @typedef {object} Closable A closable object
- * @property {() => Promise<void>} close Terminate the object
+ * @property {() => PromiseVow<void>} close Terminate the object
  */
 
 /**
  * @typedef {object} Protocol The network Protocol
- * @property {(prefix: Endpoint) => Promise<Port>} bind Claim a port, or if
+ * @property {(prefix: Endpoint) => PromiseVow<Port>} bind Claim a port, or if
  *   ending in ENDPOINT_SEPARATOR, a fresh name
  */
 
@@ -24,14 +31,14 @@
  * @typedef {object} Port A port that has been bound to a protocol
  * @property {() => Endpoint} getLocalAddress Get the locally bound name of this
  *   port
- * @property {(acceptHandler: ListenHandler) => Promise<void>} addListener
+ * @property {(acceptHandler: ListenHandler) => PromiseVow<void>} addListener
  *   Begin accepting incoming connections
  * @property {(
  *   remote: Endpoint,
  *   connectionHandler?: ConnectionHandler,
- * ) => Promise<Connection>} connect
+ * ) => PromiseVow<Connection>} connect
  *   Make an outbound connection
- * @property {(acceptHandler: ListenHandler) => Promise<void>} removeListener
+ * @property {(acceptHandler: ListenHandler) => PromiseVow<void>} removeListener
  *   Remove the currently-bound listener
  * @property {() => void} revoke Deallocate the port entirely, removing all
  *   listeners and closing all active connections
@@ -39,25 +46,25 @@
 
 /**
  * @typedef {object} ListenHandler A handler for incoming connections
- * @property {(port: Port, l: ListenHandler) => Promise<void>} [onListen] The
+ * @property {(port: Port, l: ListenHandler) => PromiseVow<void>} [onListen] The
  *   listener has been registered
  * @property {(
  *   port: Port,
  *   localAddr: Endpoint,
  *   remoteAddr: Endpoint,
  *   l: ListenHandler,
- * ) => Promise<ConnectionHandler>} onAccept
+ * ) => PromiseVow<ConnectionHandler>} onAccept
  *   A new connection is incoming
  * @property {(
  *   port: Port,
  *   localAddr: Endpoint,
  *   remoteAddr: Endpoint,
  *   l: ListenHandler,
- * ) => Promise<void>} [onReject]
+ * ) => PromiseVow<void>} [onReject]
  *   The connection was rejected
- * @property {(port: Port, rej: any, l: ListenHandler) => Promise<void>} [onError]
+ * @property {(port: Port, rej: any, l: ListenHandler) => PromiseVow<void>} [onError]
  *   There was an error while listening
- * @property {(port: Port, l: ListenHandler) => Promise<void>} [onRemove] The
+ * @property {(port: Port, l: ListenHandler) => PromiseVow<void>} [onRemove] The
  *   listener has been removed
  */
 
@@ -66,9 +73,9 @@
  * @property {(
  *   packetBytes: Data,
  *   opts?: Record<string, any>,
- * ) => Promise<Bytes>} send
+ * ) => PromiseVow<Bytes>} send
  *   Send a packet on the connection
- * @property {() => Promise<void>} close Close both ends of the connection
+ * @property {() => PromiseVow<void>} close Close both ends of the connection
  * @property {() => Endpoint} getLocalAddress Get the locally bound name of this
  *   connection
  * @property {() => Endpoint} getRemoteAddress Get the name of the counterparty
@@ -81,20 +88,20 @@
  *   localAddr: Endpoint,
  *   remoteAddr: Endpoint,
  *   c: ConnectionHandler,
- * ) => void} [onOpen]
+ * ) => PromiseVow<void>} [onOpen]
  *   The connection has been opened
  * @property {(
  *   connection: Connection,
- *   packetBytes: Bytes,
+ *   ack: Bytes,
  *   c: ConnectionHandler,
  *   opts?: Record<string, any>,
- * ) => Promise<Data>} [onReceive]
+ * ) => PromiseVow<Data>} [onReceive]
  *   The connection received a packet
  * @property {(
  *   connection: Connection,
  *   reason?: CloseReason,
  *   c?: ConnectionHandler,
- * ) => Promise<void>} [onClose]
+ * ) => PromiseVow<void>} [onClose]
  *   The connection has been closed
  *
  * @typedef {any | null} CloseReason The reason a connection was closed
@@ -110,36 +117,36 @@
 /**
  * @typedef {object} ProtocolHandler A handler for things the protocol
  *   implementation will invoke
- * @property {(protocol: ProtocolImpl, p: ProtocolHandler) => Promise<void>} onCreate
+ * @property {(protocol: ProtocolImpl, p: ProtocolHandler) => PromiseVow<void>} onCreate
  *   This protocol is created
- * @property {(localAddr: Endpoint, p: ProtocolHandler) => Promise<string>} generatePortID
+ * @property {(localAddr: Endpoint, p: ProtocolHandler) => PromiseVow<string>} generatePortID
  *   Create a fresh port identifier for this protocol
  * @property {(
  *   port: Port,
  *   localAddr: Endpoint,
  *   p: ProtocolHandler,
- * ) => Promise<void>} onBind
+ * ) => PromiseVow<void>} onBind
  *   A port will be bound
  * @property {(
  *   port: Port,
  *   localAddr: Endpoint,
  *   listenHandler: ListenHandler,
  *   p: ProtocolHandler,
- * ) => Promise<void>} onListen
+ * ) => PromiseVow<void>} onListen
  *   A port was listening
  * @property {(
  *   port: Port,
  *   localAddr: Endpoint,
  *   listenHandler: ListenHandler,
  *   p: ProtocolHandler,
- * ) => Promise<void>} onListenRemove
+ * ) => PromiseVow<void>} onListenRemove
  *   A port listener has been reset
  * @property {(
  *   port: Port,
  *   localAddr: Endpoint,
  *   remote: Endpoint,
  *   p: ProtocolHandler,
- * ) => Promise<Endpoint>} [onInstantiate]
+ * ) => PromiseVow<Endpoint>} [onInstantiate]
  *   Return unique suffix for local address
  * @property {(
  *   port: Port,
@@ -147,36 +154,36 @@
  *   remote: Endpoint,
  *   c: ConnectionHandler,
  *   p: ProtocolHandler,
- * ) => Promise<AttemptDescription>} onConnect
+ * ) => PromiseVow<AttemptDescription>} onConnect
  *   A port initiates an outbound connection
  * @property {(
  *   port: Port,
  *   localAddr: Endpoint,
  *   p: ProtocolHandler,
- * ) => Promise<void>} onRevoke
+ * ) => PromiseVow<void>} onRevoke
  *   The port is being completely destroyed
  *
  * @typedef {object} InboundAttempt An inbound connection attempt
- * @property {(desc: AttemptDescription) => Promise<Connection>} accept
+ * @property {(desc: AttemptDescription) => PromiseVow<Connection>} accept
  *   Establish the connection
  * @property {() => Endpoint} getLocalAddress Return the local address for this
  *   attempt
  * @property {() => Endpoint} getRemoteAddress Return the remote address for
  *   this attempt
- * @property {() => Promise<void>} close Abort the attempt
+ * @property {() => PromiseVow<void>} close Abort the attempt
  *
  * @typedef {object} ProtocolImpl Things the protocol can do for us
- * @property {(prefix: Endpoint) => Promise<Port>} bind Claim a port, or if
+ * @property {(prefix: Endpoint) => PromiseVow<Port>} bind Claim a port, or if
  *   ending in ENDPOINT_SEPARATOR, a fresh name
  * @property {(
  *   listenAddr: Endpoint,
  *   remoteAddr: Endpoint,
- * ) => Promise<InboundAttempt>} inbound
+ * ) => PromiseVow<InboundAttempt>} inbound
  *   Make an attempt to connect into this protocol
  * @property {(
  *   port: Port,
  *   remoteAddr: Endpoint,
  *   connectionHandler: ConnectionHandler,
- * ) => Promise<Connection>} outbound
+ * ) => PromiseVow<Connection>} outbound
  *   Create an outbound connection
  */

package/tsconfig.json

@@ -2,6 +2,7 @@
   "extends": "../../tsconfig.json",
   "compilerOptions": {
     "checkJs": false,
+    "maxNodeModuleJsDepth": 1,
   },
   "include": [
     "*.js",

package/typedoc.json

@@ -0,0 +1,9 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "./src/index.js",
+        "./src/types.js",
+    ]
+}