systemlynx 1.1.0

package/API.md

@@ -0,0 +1,142 @@
+**IN WORKING PROGRESS**
+
+# SystemLynx API Documentation
+
+Welcome to the docs! Following is a list of the objects used and created when developing web APIs with SystemLynx. SystemLynx is an end-to-end framework for developing modular, microservices software systems in NodeJS. Check out [**Quick Start**](https://github.com/Odion100/SystemLynx#quick-start) for an example of how simple it is to develope object-orientated APIs with SystemLynx.
+
+<details>
+   <summary><b><a href="https://github.com/Odion100/SystemLynx/blob/tasksjs2.0/API.md#app">App</a></b></summary>
+    
+- [**startService(options)**](https://github.com/Odion100/SystemLynx/blob/tasksjs2.0/API.md#appstartserviceoptions) 
+- [**loadService(name, url)**](https://github.com/Odion100/SystemLynx/blob/tasksjs2.0/API.md#apploadserviceurl) 
+- [**onLoad(callback)**](https://github.com/Odion100/SystemLynx/tasksjs2.0/API.md#apponloadcallback) 
+- [**ServerModule(name, constructor [,reserved_methods])**]() 
+- [**Module(name, constructor)**](https://github.com/Odion100/SystemLynx/tasksjs2.0/API.md#appmodulename-constructor) 
+- [**config(constructor)**](https://github.com/Odion100/SystemLynx/tasksjs2.0/API.md#appconfigconstructor) 
+- [**on(event, callback)**]() 
+- [**emit(event, payload)**]()
+
+</details>
+
+<details>
+   <summary><b><a href="https://github.com/Odion100/SystemLynx/tasksjs2.0/API.md#client">Client</a></b></summary>
+    
+- [**loadService(url)**]()
+
+</details>
+
+<details>
+   <summary><b><a href="https://github.com/Odion100/SystemLynx/tasksjs2.0/API.md#service">Service</a></b></summary>
+    
+- [**startService(options)**]() 
+- [**ServerModule(name, constructor [,options])**]() 
+- [**Server()**]() 
+- [**WebSocket()**]()
+
+</details>
+
+<details>
+   <summary><b><a href="https://github.com/Odion100/SystemLynx/tasksjs2.0/API.md#service">LoadBalancer</a></b></summary>
+    
+- [**startService(options)**]() 
+- [**ServerModule(name, constructor [,options])**]() 
+- [**Server()**]() 
+- [**WebSocket()**]() 
+- [**clones**]()
+  - [**register(options)**]()  
+  - [**dispatch(event)**]()
+  - [**assignDispatch(event)**]()
+
+</details>
+
+---
+
+<details>
+   <summary><b><a href="https://github.com/Odion100/SystemLynx/tasksjs2.0/API.md">ClientModule</a></b></summary>
+    
+- [**[created_method]([args...] [,callback])**]() 
+- [**on(name, constructor [,options])**]() 
+- [**emit()**]()
+
+</details>
+
+<details>
+   <summary><b><a href="https://github.com/Odion100/SystemLynx/tasksjs2.0/API.md">ServerModule</a></b></summary>
+    
+- [**[created_method]([args...] [,callback])**]() 
+- [**on(name, constructor [,options])**]() 
+- [**emit()**]()
+
+</details>
+
+---
+
+## App
+
+**App** combinds the both functionalites of SystemLynx Service and Client into one object, while also providing a module interface and lifecycle events. Access the App instance by deconcatanating from the object return when loading SystemLynx `require("sht-tasks")`.
+
+```javascript
+const { App } = require("sht-tasks");
+```
+
+## App.ServerModule(name, constructor [,reserved_methods])
+
+Use **App.ServerModule(name, constructor)** function to create or pass an object that can be loaded by a SystemLynx Client.
+
+- **_name_** (string) - name assigned to the module or object
+- **_constructor_** (object/function) -
+
+## App.startService(options)
+
+## App.loadService(name, url)
+
+## App.onLoad(callback)
+
+## App.Module(name, constructor)
+
+## App.config(constructor)
+
+---
+
+## Client
+
+## Client.loadService(url)
+
+---
+
+## Service
+
+Service is a SystemLynx abstraction used to server objects that can be loaded by a SystemLynx Client using the `Client.loadService(url)` method.
+
+Call require("sht-tasks") and de-concatenate from the object it returns.
+
+```javascript
+const { Service } = require("sht-tasks");
+```
+
+The Service object has the following methods:
+
+- **_Service.ServerModule(name, constructor [,reserved_methods])_** - Used to create or pass an object that is hosted by the Service.
+- **_Service.startService(options)_** - Used
+- **_Service.Server()_** - Returns the expressJS app instance used to handle routing to the _Services_.
+- **_Service.WebSocket()_** - Returns socket.io WebSocket instance used to emit events from the _Services_.
+
+## Service.ServerModule(name, constructor [,reserved_methods])
+
+- **Name** - String -
+  Use the `Service.ServerModule(name, constructor, [,options])` method to register an object to be hosted by a _SystemLynx Service_. This will allows you to load an instance of that object onto a client application, and call any methods on that object remotely.
+
+```javascript
+const { Service } = require("sht-tasks");
+
+const Users = {};
+
+Users.add = function (data, callback) {
+  console.log(data);
+  callback(null, { message: "You have successfully called the Users.add method" });
+};
+```
+
+Service.startService
+
+---

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Odion100
+
+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/README.md

@@ -0,0 +1,180 @@
+# SystemLynx ![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg) ![PRs Welcome](https://img.shields.io/badge/PRs-welcome-blue.svg) ![JS 100%](https://img.shields.io/badge/JavaScript-100%25-green)
+
+SystemLynx is a framework for developing modular web APIs. It's a wrapper on top of ExpressJS and Socket.io. With SystemLynx, instead of creating a server with many endpoints, you can simply export objects from the server to the client application. Basically any objects added to a SystemLynx Service can be loaded and used by a SystemLynx Client.
+
+SystemLynx comes with the following objects that are used for web API development:
+
+```javascript
+const { App, Service, Client, LoadBalancer } = require("sht-tasks");
+```
+
+Call `require("sht-tasks")` and de-concatenate from the object it returns. The main abstractions used for client-to-server interactions are the following:
+
+- **Service** - Used to create and host objects that can be loaded and used by a SystemLynx Client.
+- **Client** - Used in a client application to load a _Service_, which contains all the objects added to the _Service_.
+- **App** - Provides a modular interface and lifecycle methods for asynchronously creating and loading _Services_.
+
+Find the full [API Documentation](https://github.com/Odion100/SystemLynx/blob/tasksjs2.0/API.md#tasksjs-api-documentation) here.
+
+---
+
+# Quick Start
+
+## Service.ServerModule(name, constructor [,options])
+
+Use the `Service.ServerModule(name, constructor/object)` method to register an object to be hosted by a _SystemLynx Service_. This will allows you to load an instance of that object onto a client application, and call any methods on that object remotely.
+
+```javascript
+const { Service } = require("sht-tasks");
+
+const Users = {};
+
+Users.add = function (data, callback) {
+  console.log(data);
+  callback(null, { message: "You have successfully called the Users.add method" });
+};
+
+Service.ServerModule("Users", Users);
+```
+
+In the code above we assigned an object to the variable `Users` and gave it an add method. The `Service.ServerModule(name, constructor/object)` function takes the name assigned to the object as the first argument and the object itself as the second argument.
+
+Alternatively, you can use a constructor function instead of an object as the second argument. In the example below we create another _ServerModule_ called
+"Orders".
+
+```javascript
+const { Service } = require("sht-tasks");
+
+const Users = {};
+
+Users.add = function (data, callback) {
+  console.log(data);
+  callback(null, { message: "You have successfully called the Users.add method" });
+};
+
+Service.ServerModule("Users", Users);
+
+Service.ServerModule("Orders", function () {
+  const Orders = this;
+
+  Orders.find = function (arg1, arg2, callback) {
+    console.log(data);
+    callback(null, { message: "You have successfully called the Orders.find method" });
+  };
+});
+```
+
+In the _ServerModule_ constructor function above, the `this` value is the initial instance of the _ServerModule_ object. Every method added to the `this` value will be accessible when the object is loaded by a _SystemLynx Client_. Notice that the method we created, `Orders.find = function(arg1, arg2, callback)...`, has 3 parameters including a callback function as the last argument. By defualt all _ServerModule_ methods will recieve a callback function as its last argument. Use the first parameter of the callback function to respond with an error, and the second parameter to send a success response. Note: _ServerModule_ methods can be configured to work with synchronous return values instead of asynchronous callbacks (read more about Service configuration [here](https://github.com/Odion100/SystemLynx/blob/tasksjs2.0/API.md#apploadserviceurl)).
+
+## Service.startService(options)
+
+Before we can access the objects hosted by this _Service_ from a client application, we need to call the `Service.startService(options)` function. This will start an **ExpressJS** Server and a **Socket.io** WebSocket Server, and set up routing for the _Service_. In the example below we added the `Service.startService(options)` function at the bottom, but the order does not matter.
+
+```javascript
+const { Service } = require("sht-tasks");
+
+const Users = {};
+
+Users.add = function (data, callback) {
+  console.log(data);
+  callback(null, { message: "You have successfully called the Users.add method" });
+};
+
+Service.ServerModule("Users", Users);
+
+Service.ServerModule("Orders", function () {
+  const Orders = this;
+
+  Orders.find = function (arg1, arg2, callback) {
+    console.log(data);
+    callback(null, { message: "You have successfully called the Orders.find method" });
+  };
+});
+
+Service.startService({ route: "test/service", port: "4400", host: "localhost" });
+```
+
+Now lets see how these objects can be loaded into a client application.
+
+## Client.loadService(url, [options])
+
+The `Client.loadService(url)` function can be used to load a SystemLynx _Service_. This method requires the url (string) of the _Service_ you want to load as the first argument, and will return a promise that will resolve into an object that containing all the modules hosted by that service. See below. **NOTE: You must be within an async function in order to use the `await` keyword when returning a promise.**
+
+```javascript
+const { Client } = require("sht-tasks");
+
+const { Users, Orders } = await Client.loadService("http://localhost:4400/test/service");
+
+console.log(Users, Orders);
+```
+
+Now that we've loaded the _Service_ that we created in the previous example, and have a handle on the _Users_ and _Orders_ objects hosted by the _Service_, we can now call any method on those objects. In the example below, we demonstrate that when a methods for the ServerModule objects is called from the client, it can optionally take a callback as the last argument or, if a callback is not used, it will return a promise. With the `Users.add(data, callback)` method we used a callback, but with the `Orders.find(arg1, arg2, callback)` method we left out the callback function and used the `await` keyword to return a promise.
+
+```javascript
+const { Client } = require("sht-tasks");
+
+const { Users, Orders } = await Client.loadService("http://localhost:4400/test/service");
+
+console.log(Users, Orders);
+
+Users.add({ message: "Users.add Test" }, function (err, results) {
+  if (err) console.log(err);
+  else console.log(results);
+});
+
+const response = await Orders.find("hello", "world");
+
+console.log(response);
+```
+
+## Sending and Receiving Websocket Events
+
+We can also receive WebSocket events emitted from the remote objects we've loaded using the `Client.loadService(url)` function. In the example below we're using the `Users.on(event_name, callback)` method to listen for events coming from the "Users" _ServerModule_.
+
+```javascript
+const { Client } = require("sht-tasks");
+
+const { Users, Orders } = await Client.loadService("http://localhost:4400/test/service");
+
+console.log(Users, Orders);
+
+Users.add({ message: "Users.add Test" }, function (err, results) {
+  if (err) console.log(err);
+  else console.log(results);
+});
+
+Users.on("new_user", function (event) {
+  console.log(event);
+});
+
+const response = await Orders.find("hello", "world");
+
+console.log(response);
+```
+
+Now let's go to our server application and call the `Users.emit(event_name, data)` method to emit a websocket event that can be received by its corresponding Clients. Below, notice that we've added `Users.emit("new_user", { message:"new_user event test" })` at the end of the `Users.add` method, so the `new_user` event will be emitted every time this method is called.
+
+```javascript
+const { Service } = require("sht-tasks");
+
+const Users = {};
+
+Users.add = function (data, callback) {
+  console.log(data);
+  callback(null, { message: "You have successfully called the Users.add method" });
+  Users.emit("new_user", { message: "new_user event test" });
+};
+
+Service.ServerModule("Users", Users);
+
+Service.ServerModule("Orders", function () {
+  const Orders = this;
+
+  Orders.find = function (arg1, arg2, callback) {
+    console.log(data);
+    callback(null, { message: "You have successfully called the Orders.find method" });
+  };
+});
+
+Service.startService({ route: "test/service", port: "4400", host: "localhost" });
+```

package/index.js

@@ -0,0 +1,40 @@
+//These are all the abstractions that make up SystemLynx
+const { isNode } = require("./utils/ProcessChecker");
+const AppFactory = require("./systemlynx/App/App");
+const LoadBalancerFactory = require("./systemlynx/LoadBalancer/LoadBalancer");
+const ServiceFactory = require("./systemlynx/Service/Service");
+const ServerManagerFactory = require("./systemlynx/ServerManager/ServerManager");
+const ClientFactory = require("./systemlynx/Client/Client");
+const HttpClientFactory = require("./systemlynx/HttpClient/HttpClient");
+const DispatcherFactory = require("./systemlynx/Dispatcher/Dispatcher");
+
+const ServerManager = isNode ? ServerManagerFactory() : null;
+const Service = isNode ? ServiceFactory() : null;
+const LoadBalancer = isNode ? LoadBalancerFactory() : null;
+
+const App = AppFactory();
+const HttpClient = HttpClientFactory();
+const Client = ClientFactory();
+const Dispatcher = DispatcherFactory();
+
+module.exports = {
+  //Export these pre-created objects for convenient object destructuring
+  //These are the main utilities for app development
+  App,
+  HttpClient,
+  LoadBalancer,
+  Client,
+  Service,
+  ServerManager,
+  Dispatcher,
+  //export all modules themselves
+  //all these modules export factory functions
+  //to ensure non-singleton behavior
+  AppFactory,
+  LoadBalancerFactory,
+  ServiceFactory,
+  ClientFactory,
+  HttpClientFactory,
+  ServerManagerFactory,
+  DispatcherFactory,
+};

package/index.test.js

@@ -0,0 +1,121 @@
+const { expect } = require("chai");
+const {
+  App,
+  HttpClient,
+  LoadBalancer,
+  Client,
+  Service,
+  ServerManager,
+  AppFactory,
+  LoadBalancerFactory,
+  ServiceFactory,
+  ClientFactory,
+  HttpClientFactory,
+  ServerManagerFactory,
+} = require("./index");
+
+describe("SystemLynx Factory functions", () => {
+  it("should return a factory functions for each SystemLynx abstraction", () => {
+    expect(AppFactory).to.be.a("function");
+    expect(LoadBalancerFactory).to.be.a("function");
+    expect(ServiceFactory).to.be.a("function");
+    expect(ClientFactory).to.be.a("function");
+    expect(HttpClientFactory).to.be.a("function");
+    expect(ServerManagerFactory).to.be.a("function");
+  });
+
+  it("should return an instance of each SystemLynx abstraction", () => {});
+});
+
+describe("SystemLynx Objects", () => {
+  it("should return a SystemLynx App", () => {
+    expect(App)
+      .to.be.an("object")
+      .that.has.all.keys(
+        "module",
+        "ServerModule",
+        "on",
+        "emit",
+        "startService",
+        "loadService",
+        "onLoad",
+        "config"
+      )
+      .that.respondsTo("module")
+      .that.respondsTo("ServerModule")
+      .that.respondsTo("on")
+      .that.respondsTo("emit")
+      .that.respondsTo("startService")
+      .that.respondsTo("loadService")
+      .that.respondsTo("onLoad")
+      .that.respondsTo("config");
+  });
+
+  it("should return a SystemLynx Client", () => {
+    expect(Client)
+      .to.be.an("object")
+      .that.has.property("loadService")
+      .that.is.a("function");
+  });
+
+  it("should return a HttpClient instance", () => {
+    expect(HttpClient)
+      .to.be.an("Object")
+      .that.has.all.keys("request", "upload")
+      .that.respondsTo("request")
+      .that.respondsTo("upload");
+  });
+
+  it("should return a SystemLynx LoadBalancer", () => {
+    expect(LoadBalancer)
+      .to.be.an("object")
+      .that.has.all.keys(
+        "startService",
+        "Server",
+        "WebSocket",
+        "defaultModule",
+        "ServerModule",
+        "clones"
+      )
+      .that.respondsTo("startService")
+      .that.respondsTo("Server")
+      .that.respondsTo("WebSocket")
+      .that.respondsTo("ServerModule");
+    expect(LoadBalancer.clones)
+      .to.be.an("object")
+      .that.has.all.keys("on", "emit", "clones", "register", "dispatch", "assignDispatch")
+      .that.respondsTo("emit")
+      .that.respondsTo("on")
+      .that.respondsTo("register")
+      .that.respondsTo("dispatch")
+      .that.respondsTo("assignDispatch")
+      .that.has.property("clones")
+      .that.is.an("array");
+  });
+
+  it("should return a SystemLynx ServerManager instance", () => {
+    expect(ServerManager)
+      .to.be.an("Object")
+      .that.has.all.keys(["startService", "addModule", "Server", "WebSocket"])
+      .that.respondsTo("startService")
+      .that.respondsTo("addModule")
+      .that.respondsTo("Server")
+      .that.respondsTo("WebSocket");
+  });
+
+  it("should return a new instance of a Service", () => {
+    expect(Service)
+      .to.be.an("object")
+      .that.has.all.keys(
+        "startService",
+        "ServerModule",
+        "Server",
+        "WebSocket",
+        "defaultModule"
+      )
+      .that.respondsTo("startService")
+      .that.respondsTo("ServerModule")
+      .that.respondsTo("Server")
+      .that.respondsTo("WebSocket");
+  });
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "systemlynx",
+  "version": "1.1.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js",
+    "test": "jest --verbose --testPathIgnorePatterns 'client-setup.test.js'"
+  },
+  "dependencies": {
+    "body-parser": "^1.18.3",
+    "chai-as-promised": "^7.1.1",
+    "express": "^4.16.4",
+    "jest": "^24.9.0",
+    "mime": "^2.4.0",
+    "multer": "^1.4.2",
+    "request": "^2.88.0",
+    "shortid": "^2.2.14",
+    "socket.io": "^2.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Odion100/SystemLynx.git"
+  },
+  "author": "odion edwards",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/Odion100/SystemLynx/issues"
+  },
+  "homepage": "https://github.com/Odion100/SystemLynx#readme",
+  "devDependencies": {
+    "chai": "^4.3.4",
+    "cz-conventional-changelog": "^3.3.0",
+    "mocha": "^6.2.0"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  }
+}

package/systemlynx/App/App.js

@@ -0,0 +1,76 @@
+"use strict";
+const { isNode } = require("../../utils/ProcessChecker");
+const ServiceFactory = require("../Service/Service");
+const SystemObject = require("./components/SystemObject");
+const Dispatcher = require("../Dispatcher/Dispatcher");
+const initializeApp = require("./components/initializeApp");
+const URL = require("url");
+
+module.exports = function SystemLynxApp() {
+  const App = Dispatcher();
+  const system = {
+    Services: [],
+    Modules: [],
+    ServerModules: [],
+    configurations: {},
+    App,
+    routing: null,
+  };
+  SystemObject.apply(system, [system]);
+  setTimeout(() => initializeApp(system), 0);
+
+  if (isNode) {
+    system.Service = ServiceFactory();
+    system.Service.defaultModule = SystemObject(system);
+
+    App.startService = (options) => {
+      system.routing = options;
+      return App;
+    };
+
+    App.ServerModule = (name, __constructor) => {
+      system.ServerModules.push({
+        name,
+        __constructor,
+      });
+      return App;
+    };
+  }
+
+  App.loadService = (name, url) => {
+    system.Services.push({
+      name,
+      url,
+      onLoad: null,
+      client: {},
+    });
+    return App;
+  };
+
+  App.onLoad = (handler) => {
+    const service = system.Services[system.Services.length - 1];
+    service.onLoad = handler;
+    return App;
+  };
+
+  App.module = (name, __constructor) => {
+    system.Modules.push({
+      name,
+      __constructor,
+      module: SystemObject(system),
+    });
+    return App;
+  };
+
+  App.config = (__constructor) => {
+    if (typeof __constructor === "function")
+      system.configurations = { __constructor, module: SystemObject(system) };
+    else
+      throw Error(
+        "App.config methods requires a constructor function as it first parameter."
+      );
+    return App;
+  };
+
+  return App;
+};

package/systemlynx/App/components/SystemObject.js

@@ -0,0 +1,9 @@
+"use strict";
+module.exports = function SystemObject(system) {
+  const App = this || {};
+  App.useModule = modName => (system.Modules.find(mod => mod.name === modName) || {}).module || {};
+  App.useService = serviceName =>
+    (system.Services.find(mod => mod.name === serviceName) || {}).client || {};
+  App.useConfig = () => system.configurations.module || {};
+  return App;
+};

package/systemlynx/App/components/initializeApp.js

@@ -0,0 +1,33 @@
+const loadModules = require("./loadModules");
+const loadServices = require("./loadServices");
+
+module.exports = async function initApp(system) {
+  let configComplete = false;
+  const continuationERROR = () => {
+    if (!configComplete)
+      console.warn(
+        `
+        continuationERROR: Failed to call continuation function in App Configuariotn module 
+        
+        Fix: Must call next function during App.config( constructor(=>next) )
+        
+        `
+      );
+  };
+
+  try {
+    await loadServices(system);
+  } catch (err) {
+    throw `(AppERROR): Initialization Error - failed to load all services`;
+  }
+
+  if (typeof system.configurations.__constructor === "function") {
+    setTimeout(continuationERROR, 0);
+    system.configurations.__constructor.apply(system.configurations.module, [
+      () => {
+        configComplete = true;
+        loadModules(system);
+      }
+    ]);
+  } else loadModules(system);
+};

package/systemlynx/App/components/loadModules.js

@@ -0,0 +1,14 @@
+const Dispatcher = require("../../Dispatcher/Dispatcher");
+
+module.exports = async function loadModules(system) {
+  system.Modules.forEach((mod) => {
+    Dispatcher.apply(mod.module);
+    mod.__constructor.apply(mod.module);
+  });
+
+  system.ServerModules.forEach(({ name, __constructor }) =>
+    system.Service.ServerModule(name, __constructor)
+  );
+  if (system.routing) await system.Service.startService(system.routing);
+  system.App.emit("init_complete", system);
+};