@caboodle-tech/node-simple-server 1.3.1 → 2.0.0

package/.eslintrc.json

@@ -1,38 +1,50 @@
 {
     "env": {
         "browser": true,
+        "commonjs": true,
         "es2021": true
     },
-    "extends": ["airbnb-base"],
+    "extends": [
+        "airbnb-base"
+    ],
+    "overrides": [],
     "parserOptions": {
-        "ecmaVersion": 12,
-        "sourceType": "module"
+        "ecmaVersion": "latest"
     },
     "rules": {
-        "comma-dangle": "off",
-        "func-names": "off",
-        "indent": ["error", 4, { "SwitchCase": 1 }],
-        "no-param-reassign": "off",
-        "no-plusplus": ["error", { "allowForLoopAfterthoughts": true }],
-        "no-template-curly-in-string": "off",
-        "no-unused-vars": "off",
-        "no-use-before-define": "off",
-        "no-restricted-syntax": [
+        "class-methods-use-this": "off",
+        "comma-dangle": [
+            "error",
+            "never"
+        ],
+        "default-case": "off",
+        "import/extensions": ["error", "always", {"ignorePackages": true} ],
+        "import/no-extraneous-dependencies": [
             "error",
             {
-                "selector": "ForInStatement",
-                "message": "for..in loops iterate over the entire prototype chain, which is virtually never what you want. Use Object.{keys,values,entries}, and iterate over the resulting array."
-            },
+                "devDependencies": true
+            }
+        ],
+        "indent": [
+            "error",
+            4,
             {
-                "selector": "LabeledStatement",
-                "message": "Labels are a form of GOTO; using them makes code confusing and hard to maintain and understand."
-            },
+                "SwitchCase": 1
+            }
+        ],
+        "max-len": ["warn", { "code": 120 }],
+        "no-plusplus": [
+            "error",
             {
-                "selector": "WithStatement",
-                "message": "`with` is disallowed in strict mode because it makes code impossible to predict and optimize."
+                "allowForLoopAfterthoughts": true
             }
         ],
-        "padded-blocks": "off",
-        "prefer-destructuring": "off"
+        "no-use-before-define": "off",
+        "padded-blocks": [
+            "error",
+            {
+                "classes": "always"
+            }
+        ]
     }
-}
+}

package/COPYING.txt

@@ -0,0 +1,7 @@
+Copyright 2023 Caboodle Tech Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/LICENSE.txt

@@ -0,0 +1,22 @@
+Commons Clause License Condition v1.0
+
+The Software is provided to you by the Licensor under the License, as defined
+below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights under the
+License will not include, and the License does not grant to you, the right to
+Sell the Software.
+
+For purposes of the foregoing, “Sell” means practicing any or all of the rights
+granted to you under the License to provide to third parties, for a fee or other
+consideration (including without limitation fees for hosting or consulting/
+support services related to the Software), a product or service whose value
+derives, entirely or substantially, from the functionality of the Software. Any
+license notice or attribution required by the License must also include this
+Commons Clause License Condition notice.
+
+Software: Node Simple Server (NSS)
+
+License: MIT
+
+Licensor: Caboodle Tech Inc.

package/README.md

@@ -1,23 +1,25 @@
 # NSS: a Node based Simple Server
 
-Node Simple Server (NSS) is a small but effective node based server for development sites and self controlled live reloading. You should consider using NSS if:
+A small but effective node based server for development sites, customizable live reloading, and websocket support built-in. You should consider using NSS if:
 
 :heavy_check_mark:  You want to add live reloading to the development process of a static site.
 
-:heavy_check_mark:  You want easy two-way communication from the back-end and front-end of your development site; WebSockets managed for you.
+:heavy_check_mark:  You want easy two-way communication from the back-end and front-end of your development site with built-in WebSockets ready for use.
 
 :heavy_check_mark:  You want more fine grained control over the whole live reloading process.
 
 :heavy_check_mark:  You want to easily test your development site on multiple devices; must be on the same LAN.
 
+:heavy_check_mark:  You want to easily setup a LAN application for educational purposes or other development; must be on the same LAN, please consider security implications.
+
 ## Installation
 
 ### Manually:
 
-Noe Simple Server (NSS) can be manually incorporated into your development process/ application. Extract the `nss` folder from the [latest release](https://github.com/caboodle-tech/node-simple-server/releases/) and then `require` the server module into your code, similar to:
+Noe Simple Server (NSS) can be manually incorporated into your development process/ application. Extract the `nss` folder from the [latest release](https://github.com/caboodle-tech/node-simple-server/releases/) and then `import` the server module into your code, similar to:
 
 ```javascript
-const NodeSimpleServer = require("./node-simple-server/server");
+import NodeSimpleServer from './nss.js';
 ```
 
 ### Locally:
@@ -25,14 +27,14 @@ const NodeSimpleServer = require("./node-simple-server/server");
 You can install and use NSS locally in a project with:
 
 ```bash
-// As a normal dependency:
+# As a normal dependency:
 npm install @caboodle-tech/node-simple-server
 
-// or as a development dependency:
+# or as a development dependency:
 npm install @caboodle-tech/node-simple-server --save-dev
 ```
 
-Depending on how you use and incorporate NSS into your project will determine what it's dependency type should be.
+Depending on how you use and incorporate NSS into your project will determine the best dependency strategy to use.
 
 ### Globally:
 
@@ -47,36 +49,65 @@ npm install --global @caboodle-tech/node-simple-server
 NSS is designed to be controlled and/or wrapped by another application. The bare minimum code needed to use NSS in your application is:
 
 ```javascript
-// Require NSS. Here it is required from a manual install.
-const NodeSimpleServer = require("./server");
+/**
+ * Import NSS. Here it is being imported from a manual install.
+ * NOTE: Manual installs must include the handlers directory one directory higher than NSS.
+ */
+import NodeSimpleServer from './nss.js';
+import path from 'path'
+
+// This is needed for ES modules.
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Determine what directory to watch for changes.
+const websiteRoot = __dirname;
+
+// Build a bare minimum server options object.
+const serverOptions = {
+    root: websiteRoot
+};
 
 // Get a new instance of NSS.
-const Server = new NodeSimpleServer();
+const Server = new NodeSimpleServer(serverOptions);
 
 // Start the server.
 Server.start();
 
-// A bare minimum callback to handle changes.
-function changes(event, path) {
-    if (event === "change") {
+// A bare minimum callback to handle most development changes.
+function watcherCallback(event, path, extension) {
+    if (extension === 'css') {
+        Server.reloadAllStyles();
+        return;
+    }
+    if (extension === 'js') {
+        /**
+         * NOTE: This is a heavy request to use if your site loads resources from
+         * other sites such as images, databases, or API calls. Consider a better
+         * approach in this cases such as throttling.
+         */
+        Server.reloadAllPages();
+        return;
+    }
+    if (event === 'change') {
         Server.reloadSinglePage(path);
     }
 }
 
 // Build a bare minimum watcher options object.
-const options = {
+const watcherOptions = {
     events: {
-        all: changes,
+        all: watcherCallback, // Just send everything to a single function.
     },
 };
 
-// Watch current directory for changes.
-Server.watch(".", options);
+// Watch the current directory for changes.
+Server.watch(websiteRoot, watcherOptions);
 ```
 
 The `options` object **required** by the `watch` method must include an `events` property with at least one watched event. The demo code above used `all` to capture any event. This object takes a lot of settings and is explained below in the **Watch Options** table.
 
-NSS uses the current working directory as the live servers root and is pre-configured with several additional default settings. You can change these by providing your own `options` object when instantiating the server. How this looks in code is shown below, the following table **Server Options** explains all available options.
+NSS uses `process.cwd()` as the live servers root if omitted and is pre-configured with several additional default settings. You can change these by providing your own `options` object when instantiating the server. How this looks in code is shown below, the following table **Server Options** explains all available options.
 
 ```javascript
 // Make your options object.
@@ -86,6 +117,8 @@ const options = {...};
 const Server = new NodeSimpleServer(options);
 ```
 
+**Note:** If you set `options.root` to a different location than the current directory, you should usually provide the same path or a child path of this path, when you instantiate `Server.watch`.
+
 ### :bookmark: Server Options (Object)
 
 #### **contentType**    default: text/html
@@ -106,7 +139,7 @@ const Server = new NodeSimpleServer(options);
 
 #### **root**    default: process.cwd()
 
--   The port number the HTTP and WebSocket server should listen on for requests.
+-   The absolute path to the directory that should be considered the servers root directory.
 
 ### :bookmark: Watch Options (Object)
 
@@ -132,7 +165,7 @@ const Server = new NodeSimpleServer(options);
 
 #### **cwd**
 
--   The base directory from which watch `paths` are to be derived. Paths emitted with events will be relative to this.
+-   The base directory from which watch `paths` are to be derived. Paths emitted with events will be relative to this path and will use only forward slashes (/) on all operating systems.
 
 #### **disableGlobbing**    default: false
 
@@ -154,9 +187,9 @@ const Server = new NodeSimpleServer(options);
 
 -   If relying upon the `fs.Stats` object that may get passed with `add`, `addDir`, and `change` events, set this to `true` to ensure it is provided even in cases where it wasn't already available from the underlying watch events.
 
-#### **depth**
+#### **depth**    default: undefined
 
--   If set, limits how many levels of subdirectories will be traversed.
+-   If set, limits how many levels of subdirectories will be traversed when watching for changes.
 
 #### **awaitWriteFinish**    default: false
 
@@ -170,12 +203,16 @@ const Server = new NodeSimpleServer(options);
 
 -   Automatically filters out artifacts that occur when using editors that use "atomic writes" instead of writing directly to the source file.
 
-Most of the **Watch Object Options** are directly from [chokidar](https://github.com/paulmillr/chokidar) which is being used to handle the file monitoring. You may want to visit the [chokidar repo](https://github.com/paulmillr/chokidar) for more information.
+Most of the **Watch Object Options** are directly from [chokidar](https://github.com/paulmillr/chokidar) which is being used to handle the file monitoring. You may want to visit the [chokidar repo](https://github.com/paulmillr/chokidar) for more information. Please note that event paths are altered by NSS to only use forward slashes (/) on all operating systems.
 
 ### :bookmark: Server Methods
 
 With your new instance of NSS you can call any of the following public methods:
 
+#### **addWebsocketCallback(pattern^, callback)**
+
+-   Register a function (`callback`) to receive messages from the front-end if the pages URL matches the `pattern`.
+
 ### **getAddresses**
 
 - Returns an array of all the IP addresses you can reach this server at either from the machine itself or on the local area network (LAN).
@@ -184,13 +221,9 @@ With your new instance of NSS you can call any of the following public methods:
 
 -   Returns an array of watcher objects showing you which directories and files are actively being watched for changes.
 
-#### **message(pattern^, msg)**
+#### **message(pageId | pattern^, msg)**
 
--   Send a message (`msg`) via WebSocket to the page or pages that match the `pattern`.
-
-#### **registerCallback(pattern^, callback)**
-
--   Register a function (`callback`) to receive messages from the front-end if the pages URL matches the `pattern`.
+-   Send a message (`msg`) via WebSocket to the page that matches the `pageId`, or send to a page or pages that match the `pattern`.
 
 #### **reloadPages()**
 
@@ -208,29 +241,29 @@ With your new instance of NSS you can call any of the following public methods:
 
 -   Sends the refreshCSS signal to all active pages.
 
-#### **start(\[port\], \[callback\])**
+#### **removeWebsocketCallback(pattern^, callback)**
 
--   Starts the HTTP and WebSocket servers. NOTE: This is a blocking process and will keep any application that ran it alive until stopped gracefully or forcefully terminated. If you do not want this behavior for any reason you will need to call this in its own process.
+-   Unregister (stop messaging) a `callback` function that was initially registered with the `pattern`.
 
-#### **stop(\[callback\])**
+#### **start(\[callback\]) | start(\[port\], \[callback\])**
 
--   Gracefully closes all HTTP and WebSocket connections and turns off the servers.
+-   Starts the HTTP and WebSocket servers and notifies `callback` if present. `Port` is meant to be an internal option for NSS only but you may specify a port number for NSS to use if you have strict requirements in your environment. NOTE: This is a blocking process and will keep any application that ran it alive until stopped gracefully or forcefully terminated. If you do not want this behavior for any reason you will need to call this in its own process.
 
-#### **unregisterCallback(pattern^, callback)**
+#### **stop(\[callback\])**
 
--   Unregister (stop messaging) a function (`callback`) that was initially registered with the `pattern`.
+-   Gracefully closes all HTTP and WebSocket connections and turns off the servers, notifying `callback` if present.
 
 #### **unwatch(paths^^)**
 
--   Stop watching directories or files for changes; previously registered with `watch`.
+-   Stop watching directories or files (`paths`) for changes previously registered with `watch`.
 
-#### **watch(paths^^, options)**
+#### **watch(paths^^, watchOptionsObject)**
 
--   Start watching a file, files, directory, or directories for changes and then callback to functions that can/ will respond to these changes.
+-   Start watching a file, files, directory, or directories (`paths`) for changes and then callback to functions set in `watchOptionsObject` that will respond to these changes.
 
 #### **watchEnd()**
 
--   Stop watching registered file, files, directory, or directories for changes.
+-   Stop watching all registered file, files, directory, or directories for changes.
 
 ### :bookmark: Symbol Key
 
@@ -240,7 +273,7 @@ With your new instance of NSS you can call any of the following public methods:
 
 ## Changelog
 
-The [current changelog is here](./changelogs/v1.md). All [other changelogs are here](./changelogs).
+The [current changelog is here](./changelogs/v2.md). All [other changelogs are here](./changelogs).
 
 ## Contributions