lws - npm Package Compare versions

Comparing version 2.0.0-9 to 2.0.0-10

index.js

@@ -6,3 +6,23 @@ const util = require('./lib/util')
 /**
+ * An application shell for building a modular HTTP, HTTPS or HTTP2 local web server.
  * @module lws
+ * @example
+ * // Middleware to handle requests
+ * class Greeter {
+ *   middleware () {
+ *     return (ctx, next) => {
+ *       ctx.body = 'Hello!'
+ *       next()
+ *     }
+ *   }
+ * }
+ *
+ * // Launch a HTTP server with the Greeter middleware attached
+ * const lws = Lws.create({ stack: Greeter })
+ *
+ * // $ curl http://127.0.0.1:8000
+ * // Hello!
+ *
+ * // shutdown
+ * lws.server.close()
  */
@@ -15,9 +35,10 @@
 class Lws extends EventEmitter {
-   /**
-    * @param {LwsConfig} - Server config.
-    */
+  /**
+   * Contructs an empty `Lws` instance but does not initialise it. Use the `Lws.create(config)` factory method to create, initialise and launch a lws server.
+   * @param {LwsConfig} - Server config.
+   */
   constructor (config) {
     super()
     /**
-     * The HTTP, HTTPS or HTTP2 server.
+     * The output of Node's standard http, https or http2 `.createServer()` method. Created and set by `lws.createServer()`.
      * @type {Server}
@@ -28,3 +49,3 @@ */
     /**
-     * The middleware plugin stack.
+     * The middleware plugin stack as defined by the config. Created and set by `lws.useMiddlewareStack()`.
      * @type {MiddlewareStack}
@@ -35,3 +56,3 @@ */
     /**
-     * Active config.
+     * The active lws config.
      * @type {LwsConfig}
@@ -45,3 +66,3 @@ */
   /**
-   * Get built-in defaults.
+   * Get built-in defaults. Overwrite this method to change the built-in defaults.
    * @returns {object}
@@ -94,3 +115,3 @@ * @ignore
   /**
-   * Create a HTTP, HTTPS or HTTP2 server, depending on config. Returns the output of Node's standard http, https or http2 `.createServer()` method.
+   * Create a HTTP, HTTPS or HTTP2 server, depending on config. Returns the output of Node's standard http, https or http2 `.createServer()` method also assigning it to `lws.server`.
    * @returns {Server}
@@ -126,3 +147,3 @@ */
   /**
-   * Attach the Middleware stack to the server.
+   * Attach the Middleware stack to the server. Must be run after `lws.createServer()`.
    */
@@ -149,3 +170,3 @@ useMiddlewareStack () {
       /**
-       * Highly-verbose debug information event stream.
+       * An event stream of debug information.
        *
@@ -165,2 +186,22 @@ * @event module:lws#verbose
 
+  /**
+   * Attach the view specified in the config.
+   */
+  useView () {
+    const config = this.config
+    if (config.view) {
+      if (typeof config.view === 'string') {
+        const ViewPlugin = require('./lib/view/view-plugin')
+        const ViewClass = ViewPlugin.load(config.view, {
+          paths: config.moduleDir,
+          prefix: config.modulePrefix
+        })
+        config.view = new ViewClass()
+      }
+      this.on('verbose', (key, value) => {
+        config.view.write(key, value, config)
+      })
+    }
+  }
+
   /* Pipe server events into 'verbose' event stream */
@@ -170,15 +211,16 @@ _propagateServerEvents () {
       const byteSize = require('byte-size')
-      return {
-        socketId: socket.id,
+      const output = {
         bytesRead: byteSize(socket.bytesRead).toString(),
-        bytesWritten: byteSize(socket.bytesWritten).toString()
+        bytesWritten: byteSize(socket.bytesWritten).toString(),
+        remoteAddress: socket.remoteAddress
       }
+      if (socket.bufferSize) {
+        output.bufferSize = byteSize(socket.bufferSize).toString()
+      }
+      return output
     }
 
-    let cId = 1
-
     /* stream connection events */
     const server = this.server
     server.on('connection', socket => {
-      socket.id = cId++
       this.emit('verbose', 'server.socket.new', socketProperties(socket))
@@ -212,7 +254,2 @@ socket.on('connect', () => {
 
-    let requestId = 1
-    server.on('request', req => {
-      req.requestId = requestId++
-    })
-
     /* on server-up message */
@@ -244,19 +281,12 @@ server.on('listening', () => {
 
+  /**
+   * Launch a listening HTTP, HTTPS or HTTP2 server configured as specified by the supplied config.
+   * @param config {LwsConfig}
+   * @returns {Lws}
+   */
   static create (config) {
     const lws = new this(config)
 
-    /* attach view */
-    if (config.view) {
-      if (typeof config.view === 'string') {
-        const ViewPlugin = require('./lib/view/view-plugin')
-        const ViewClass = ViewPlugin.load(config.view, {
-          paths: config.moduleDir,
-          prefix: config.modulePrefix
-        })
-        config.view = new ViewClass()
-      }
-      lws.on('verbose', (key, value) => {
-        config.view.write(key, value, config)
-      })
-    }
+    /* attach the view */
+    lws.useView()
 
@@ -263,0 +293,0 @@ /* create a HTTP, HTTPS or HTTP2 server */

lib/config.js

 /**
+ * The lws configuration options.
  * @module lws-config
  */
 
-
 /**
@@ -7,0 +7,0 @@ * @alias module:lws-config

lib/middleware-plugin.js

@@ -40,4 +40,4 @@ /**
    * Return one of more Koa middleware functions. Optionally, emit `verbose` events to `ctx.app`.
-   * @params {object} - The active config object.
-   * @params {Lws} - The active `lws` instance.
+   * @param {object} - The active config object.
+   * @param {Lws} - The active `lws` instance.
    * @returns {function|function[]}
@@ -44,0 +44,0 @@ */

lib/server-factory/https.js

@@ -27,5 +27,3 @@ const HttpFactory = require('./http')
     }
-    if (Object.keys(serverOptions).length) {
-      this.emit('verbose', 'server.config', serverOptions)
-    }
+    this.emit('verbose', 'server.config', serverOptions)
     return server
@@ -32,0 +30,0 @@ }

lib/view/cli-view.js

@@ -0,7 +1,13 @@
+const _log = new WeakMap()
+const _logError = new WeakMap()
+
 class CliView {
-  constructor (options) {
-    options = options || {}
-    this.options = options
-    this.events = []
-    this.logError = options.logError || console.error
+  /**
+   * @param [options] {object}
+   * @param [options.log] {function}
+   * @param [options.logError] {function}
+   */
+  constructor (options = {}) {
+    _log.set(this, options.log || console.log)
+    _logError.set(this, options.logError || console.error)
   }
@@ -36,16 +42,15 @@
       .join(', ')
-    this.logError(`Listening at ${ipList}`)
+    _logError.get(this)(`Listening on ${ipList}`)
   }
 
-  write (key, value, options) {
-    options = options || {}
+  write (key, value, config = {}) {
     if (key === 'middleware.error') {
       const { printError } = require('../util')
-      printError(value, 'Middleware error', options.logError)
+      printError(value, 'Middleware error', _logError.get(this))
     } else if (key === 'server.listening') {
       this.printListeningMsg(value)
     } else {
-      if (options.verbose || options.verboseInclude || options.verboseExclude) {
-        const verboseInclude = options.verboseInclude
-        const verboseExclude = options.verboseExclude
+      if (config.verbose || config.verboseInclude || config.verboseExclude) {
+        const verboseInclude = config.verboseInclude
+        const verboseExclude = config.verboseExclude
         let printThis = true
@@ -62,3 +67,3 @@ if (verboseInclude && verboseInclude.length) {
           output[key] = value
-          const log = options.log || console.log
+          const log = _log.get(this)
           log(util.inspect(output, {
@@ -65,0 +70,0 @@ depth: 6,

lib/view/view-plugin.js

@@ -5,3 +5,3 @@ /**
 
- /**
+/**
   * @alias module:view-plugin
@@ -8,0 +8,0 @@ */

package.json

 {
   "name": "lws",
   "author": "Lloyd Brookes <[e-mail]>",
-  "version": "2.0.0-9",
+  "version": "2.0.0-10",
   "description": "The modular web server for productive full-stack development",
@@ -25,3 +25,3 @@ "repository": "https://github.com/lwsjs/lws.git",
     "cover": "TESTOPEN=true nyc -r html -r text npm test && nyc report --reporter=text-lcov | coveralls",
-    "docs": "jsdoc2md lib/middleware-plugin.js > doc/middleware-plugin.md && jsdoc2md index.js > doc/lws.md && jsdoc2md lib/view/view-plugin.js > doc/view-plugin.md && jsdoc2md lib/config.js > doc/config.md"
+    "docs": "jsdoc2md lib/middleware-plugin.js > doc/middleware-plugin.md && jsdoc2md --private index.js > doc/lws.md && jsdoc2md lib/view/view-plugin.js > doc/view-plugin.md && jsdoc2md lib/config.js > doc/config.md"
   },
@@ -28,0 +28,0 @@ "files": [

README.md

@@ -10,14 +10,20 @@ [![view on npm](https://img.shields.io/npm/v/lws.svg)](https://www.npmjs.org/package/lws)
 
-**Documentation work in progress.**
+***This documentation is a work in progress.***
 
-Lws is tool designed for quickly launching a personalised Node.js HTTP, HTTPS or HTTP2 server on the command line. It's intended to facilitate rapid, full-stack Javascript development.
+A tool for quickly launching a personalised Node.js HTTP, HTTPS or HTTP2 local web server. It's intended to facilitate rapid, full-stack Web Platform development.
 
-On top of launching a server you can:
+Its has a very lean core - behaviour is added via plugins giving you full control over what features are activated, how HTTP requests are handled, responses created, caches controlled, activity visualised etc.
 
-* Attach one or more middleware plugins to handle requests in the manner desired.
-* Attach a view to visualise activity
+Core features.
+
+* Launch an HTTP, HTTPS or HTTP2 server.
+* Use one or more custom or pre-built middleware plugins to attach the behaviour required by your project.
+* Attach a custom view to personalise how activity is visualised.
 * Store config at any level - project, user or system.
+* Programmatic and command-line APIs.
 
 ## Synopsis
 
+### Core usage
+
 Launch an HTTP server on the default port of 8000.
@@ -30,6 +36,16 @@
 
-Add some middleware to serve static files and directory listings.
+For HTTPS or HTTP2, pass the `--https` or `--http2` flags respectively.
 
 ```
+$ lws --http2
+Listening at https://mba4.local:8000, https://127.0.0.1:8000, https://192.168.0.200:8000
+```
+
+### Using middleware plugins
+
+Install and use some middleware to serve static files and directory listings.
+
+```
 $ npm install --save-dev lws-static lws-index
+
 $ lws --stack lws-static lws-index
@@ -39,6 +55,51 @@ Listening at http://mba4.local:8000, http://127.0.0.1:8000, http://192.168.0.200:8000
 
-The file system from the current directory will now be available to explore at http://127.0.0.1:8000.
+The current directory will now be available to explore at `http://127.0.0.1:8000`.
 
+Install and use logging middleware. Note the `lws-` prefix is optional when supplying module names to `--stack`.
+
+```
+$ npm install --save-dev lws-log
+
+$ lws --stack log static index --log.format combined
+Listening at http://mba4.local:8000, http://127.0.0.1:8000, http://192.168.0.200:8000
+::ffff:127.0.0.1 - GET /lws.config.js HTTP/1.1 200 52 - 8.259 ms
+::ffff:127.0.0.1 - GET /package.json HTTP/1.1 200 399 - 1.478 ms
+```
+
+### Creating a custom middleware plugin
+
+Lws uses [Koa](https://github.com/koajs/koa/) as its middleware engine. Here is a trivial plugin example, save the following code as `example-middleware.js`:
+
+```js
+class ExamplePlugin {
+  middleware () {
+    return function (ctx) {
+      ctx.body = 'Hello from lws!'
+    }
+  }
+}
+
+module.exports = ExamplePlugin
+```
+
+Now launch an HTTP server using this middleware.
+
+```
+$ lws --stack example-middleware.js
+Listening at http://mba4.local:8000, http://127.0.0.1:8000, http://192.168.0.200:8000
+
+$ curl http://127.0.0.1:8000
+Hello from lws!
+```
+
+## Documentation 
+
+* [Tutorials](https://github.com/lwsjs/lws/wiki)
+* API Reference
+    * [Lws](https://github.com/lwsjs/lws/blob/master/doc/lws.md)
+    * [Middleware plugin](https://github.com/lwsjs/lws/blob/master/doc/middleware-plugin.md)
+    * [View plugin](https://github.com/lwsjs/lws/blob/master/doc/view-plugin.md)
+
 * * *
 
 &copy; 2016-19 Lloyd Brookes \<[e-mail]\>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

96160

increased by3.45%

Lines of code

1061

increased by3.31%

Number of lines in readme file

103

increased by145.24%

No dependency changes