refactor: add support for built-in server options and rename functions

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: passed
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: passed
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: passed
  - task: lint_javascript_tests
    status: passed
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: passed
  - task: lint_license_headers
    status: passed
---

Author: kgryte

lib/node_modules/@stdlib/net/http-server/README.md

@@ -20,24 +20,29 @@ limitations under the License.
 
 # HTTP Server
 
-> [HTTP][http] server.
+> [HTTP][nodejs-http] server.
 
 <section class="usage">
 
 ## Usage
 
 ```javascript
-var httpServer = require( '@stdlib/net/http-server' );
+var httpServerFactory = require( '@stdlib/net/http-server' );
 ```
 
-#### httpServer( \[options,] \[ requestListener] )
+#### httpServerFactory( \[options,] \[ requestListener] )
 
-Returns a function to create an [HTTP][http] server.
+Returns a function to create an [HTTP][nodejs-http] server.
 
 ```javascript
-var createServer = httpServer();
+var httpServer = httpServerFactory();
 ```
 
+The function supports the following parameters:
+
+-   **options**: options.
+-   **requestListener**: callback to invoke upon receiving an HTTP request.
+
 To bind a request callback to a server, provide a `requestListener`.
 
 ```javascript
@@ -46,25 +51,25 @@ function requestListener( request, response ) {
     response.end( 'OK' );
 }
 
-var createServer = httpServer( requestListener );
+var httpServer = httpServerFactory( requestListener );
 ```
 
-The function accepts the following `options`:
+The function accepts the following options:
 
 -   **port**: server port. Default: `0` (i.e., randomly assigned).
 -   **maxport**: max server port when port hunting. Default: `maxport=port`.
 -   **hostname**: server hostname.
 -   **address**: server address. Default: `127.0.0.1`.
 
-To specify server options, provide an `options` object.
+To specify server options, provide an options object.
 
 ```javascript
 var opts = {
     'port': 7331,
     'address': '0.0.0.0'
 };
 
-var createServer = httpServer( opts );
+var httpServer = httpServerFactory( opts );
 ```
 
 To specify a range of permissible ports, set the `maxport` option.
@@ -74,14 +79,14 @@ var opts = {
     'maxport': 9999
 };
 
-var createServer = httpServer( opts );
+var httpServer = httpServerFactory( opts );
 ```
 
 When provided a `maxport` option, a created server will search for the first available `port` on which to listen, starting from `port`.
 
-#### createServer( done )
+#### httpServer( \[options,] done )
 
-Creates an [HTTP][http] server.
+Creates an [HTTP][nodejs-http] server.
 
 ```javascript
 function done( error, server ) {
@@ -92,11 +97,16 @@ function done( error, server ) {
     server.close();
 }
 
-var createServer = httpServer();
+var httpServer = httpServerFactory();
 
-createServer( done );
+httpServer( done );
 ```
 
+The function supports the following parameters:
+
+-   **options**: server options which are passed directly to [`http.createServer`][nodejs-http-create-server]. Which options are supported depends on the Node.js version. Older Node.js versions (e.g., <= v8.12.0) do not support an options object, and, for those versions, a provided options object is ignored.
+-   **done**: callback to invoke once a server is listening and ready to handle requests.
+
 </section>
 
 <!-- /.usage -->
@@ -122,7 +132,7 @@ createServer( done );
 ```javascript
 var proc = require( 'process' );
 var http = require( 'http' );
-var httpServer = require( '@stdlib/net/http-server' );
+var httpServerFactory = require( '@stdlib/net/http-server' );
 
 function done( error, server ) {
     if ( error ) {
@@ -149,10 +159,10 @@ var opts = {
 };
 
 // Create a function for creating an HTTP server...
-var createServer = httpServer( opts, onRequest );
+var httpServer = httpServerFactory( opts, onRequest );
 
 // Create a server:
-createServer( done );
+httpServer( done );
 ```
 
 </section>
@@ -171,7 +181,9 @@ createServer( done );
 
 <section class="links">
 
-[http]: https://nodejs.org/api/http.html
+[nodejs-http]: https://nodejs.org/api/http.html
+
+[nodejs-http-create-server]: https://nodejs.org/api/http.html#httpcreateserveroptions-requestlistener
 
 </section>
 

lib/node_modules/@stdlib/net/http-server/docs/repl.txt

@@ -24,34 +24,37 @@
 
     Returns
     -------
-    createServer: Function
+    httpServer: Function
         Function to create an HTTP server.
 
     Examples
     --------
     // Basic usage:
-    > var createServer = {{alias}}()
+    > var httpServer = {{alias}}()
     <Function>
 
     // Provide a request callback:
     > function onRequest( request, response ) {
     ...    console.log( request.url );
     ...    response.end( 'OK' );
     ... };
-    > createServer = {{alias}}( onRequest )
+    > httpServer = {{alias}}( onRequest )
     <Function>
 
     // Specify a specific port:
     > var opts = { 'port': 7331 };
-    > createServer = {{alias}}( opts )
+    > httpServer = {{alias}}( opts )
     <Function>
 
 
-createServer( done )
+httpServer( [options,] done )
     Creates an HTTP server.
 
     Parameters
     ----------
+    options: Object (optional)
+        Server options which are passed directly to `http.createServer`.
+
     done: Function
         Callback to invoke after creating a server.
 
@@ -64,8 +67,8 @@ createServer( done )
     ...    console.log( 'Success!' );
     ...    server.close();
     ... };
-    > var createServer = {{alias}}();
-    > createServer( done );
+    > var httpServer = {{alias}}();
+    > httpServer( done );
 
     See Also
     --------

lib/node_modules/@stdlib/net/http-server/docs/types/index.d.ts

@@ -104,7 +104,7 @@ type Callback = Nullary | Unary | Binary;
 *
 * @param done - callback to invoke after creating the server
 */
-type createServer = ( done: Callback ) => void;
+type httpServer = ( done: Callback ) => void; // FIXME: need to allow for an `options` argument with support for built-in server options
 
 /**
 * Returns a function which creates an HTTP server.
@@ -113,16 +113,16 @@ type createServer = ( done: Callback ) => void;
 * @returns function which creates an HTTP server
 *
 * @example
-* var createServer = httpServer();
+* var httpServer = factory();
 *
 * @example
 * function onRequest( request, response ) {
 *     console.log( request.url );
 *     response.end( 'OK' );
 * }
-* var createServer = httpServer( onRequest );
+* var httpServer = factory( onRequest );
 */
-declare function httpServer( requestListener?: RequestListener ): createServer;
+declare function factory( requestListener?: RequestListener ): httpServer;
 
 /**
 * Returns a function which creates an HTTP server.
@@ -141,7 +141,7 @@ declare function httpServer( requestListener?: RequestListener ): createServer;
 *     'port': 7331,
 *     'address': '0.0.0.0'
 * };
-* var createServer = httpServer( opts );
+* var httpServer = factory( opts );
 *
 * @example
 * var opts = {
@@ -152,11 +152,11 @@ declare function httpServer( requestListener?: RequestListener ): createServer;
 *     console.log( request.url );
 *     response.end( 'OK' );
 * }
-* var createServer = httpServer( opts, onRequest );
+* var httpServer = factory( opts, onRequest );
 */
-declare function httpServer( options: Options, requestListener?: RequestListener ): createServer;
+declare function factory( options: Options, requestListener?: RequestListener ): httpServer;
 
 
 // EXPORTS //
 
-export = httpServer;
+export = factory;