Feature: add onListening hook (#69)

* Add onListening option, call in server callback

* Add test for verifying onListening executed within timeout

* Add onListening to documentation

* Update onListening docs showing how to access other options

* Format

Author: filoxo

README.md

@@ -94,6 +94,15 @@ serve({
   mimeTypes: {
     'application/javascript': ['js_commonjs-proxy']
   }
+
+  // execute function after server has begun listening
+  onListening: function (server) {
+    const address = server.getAddress()
+    const host = address.host === '::' ? 'localhost' : address.host
+    // by using a bound function, we can access options as `this`
+    const protocol = this.https ? 'https' : 'http'
+    console.log(`Server listening at ${protocol}://${host}:${address.port}/`)
+  }
 })
 ```
 

src/index.js

@@ -21,6 +21,7 @@ function serve (options = { contentBase: '' }) {
   options.headers = options.headers || {}
   options.https = options.https || false
   options.openPage = options.openPage || ''
+  options.onListening = options.onListening || function noop () { }
   mime.default_type = 'text/plain'
 
   if (options.mimeTypes) {
@@ -74,9 +75,15 @@ function serve (options = { contentBase: '' }) {
 
   // If HTTPS options are available, create an HTTPS server
   if (options.https) {
-    server = createHttpsServer(options.https, requestListener).listen(options.port, options.host)
+    server = createHttpsServer(options.https, requestListener)
+    server.listen(options.port, options.host, () => {
+      options.onListening(server)
+    })
   } else {
-    server = createServer(requestListener).listen(options.port, options.host)
+    server = createServer(requestListener)
+    server.listen(options.port, options.host, () => {
+      options.onListening(server)
+    })
   }
 
   // Assemble url for error and info messages
@@ -178,6 +185,7 @@ export default serve
  * @property {string|boolean} [historyApiFallback] Path to fallback page. Set to `true` to return index.html (200) instead of error page (404)
  * @property {string} [host='localhost'] Server host (default: `'localhost'`)
  * @property {number} [port=10001] Server port (default: `10001`)
+ * @property {function} [onListening] Execute a function when server starts listening for connections on a port
  * @property {ServeOptionsHttps} [https=false] By default server will be served over HTTP (https: `false`). It can optionally be served over HTTPS
  * @property {{[header:string]: string}} [headers] Set headers
  */

test/rollup.config.js

@@ -1,5 +1,18 @@
 import serve from '../src/index.js'
 
+const testOnListening = () => {
+  const timeout = 3
+  const timer = setTimeout(() => {
+    const msg = `onListening was not called within ${timeout}s`
+    console.error(msg)
+    throw new Error(msg)
+  }, timeout * 1000)
+  return (server) => {
+    clearTimeout(timer)
+    console.log('onListening works', server.address())
+  }
+}
+
 export default {
   input: 'entry.js',
   output: {
@@ -11,7 +24,8 @@ export default {
       open: true,
       openPage: '/frames.html',
       historyApiFallback: '/fallback.html',
-      contentBase: ['.', 'base1', 'base2']
+      contentBase: ['.', 'base1', 'base2'],
+      onListening: testOnListening(),
     })
   ]
 }