@projectinvicta/nails 2.0.15 → 3.0.0

package/README.md

@@ -1,33 +1,34 @@
-# Nails-Boilerplate: A Node Webservice Framework
+# Nails: A Node Webservice Framework
 
-This framework is designed to provide a lightweight, configurable MVC backend
-for node developers.  With minimal dependencies, Nails offers a greater
-syntactical familiarity than php alongside the creative freedom of well developed
-server framework solutions like Rails and Django.
+Nails is a lightweight, configurable MVC-inspired backend framework for Node.js. With minimal dependencies, Nails offers a familiar syntax for developers coming from frameworks like Ruby on Rails or Django, while providing the flexibility of JavaScript.
 
-This boilerplate offers the basic necessities to get your MVC site off the ground.
-The modules used in Nails Boilerplate can be easily extended to produce the custom
-functionality to fit your needs, and you are encouraged to do so.
+Nails provides the essential building blocks to get your MVC-style application up and running quickly. The modules used in Nails can be easily extended to produce the custom functionality to fit your needs, and you are encouraged to do so.
 
-## Install
+## Getting Started
 
-```
-sudo npm install -g nails-boilerplate
+There are two recommended ways to get started with Nails.
 
-nails init <app_name>
+### Using NPX (Recommended)
+You can create a new Nails project without a global installation using `npx`:
+
+```bash
+npx @projectinvicta/nails init <app_name>
 ```
 
-This will initialize a barebones app in the directory of the same name.  Take a
-look at the self-documented config files and example controller and view before
-getting started.  Additional controllers and views will automatically be imported
-into nails.  Now just hook the new controllers in with some new routes and you're
-off to a good start.
+### Using Global Install
+Alternatively, you can install the package globally:
 
+```bash
+npm install -g @projectinvicta/nails
+
+nails init <app_name>
 ```
-cd app_name
 
-npm install
+After initializing your app, navigate into the new directory and start the server:
 
+```bash
+cd <app_name>
+npm install
 npm start
 ```
 
@@ -36,15 +37,15 @@ npm start
 For your convenience, here is a quick outline of the main components of a nails service.
 Remember: each object comes with an example file to use for reference when building your service.
 
-### Config
-Your configuration files are stored in app_name/config/. There are three default config files:
-
-```
-service.js
-routes.js
-db.js
+### Named Exports
+`nails` now provides a number of useful named exports. You can import them as follows:
+```js
+import Nails, { Controller, Model, DataTypes, /* config types */ } from '@projectinvicta/nails';
 ```
 
+### Config
+Your configuration files are stored in app_name/config/.
+
 Each default config file is annotated with comments documenting each field to
 help you tailor your service to your needs.
 
@@ -65,7 +66,7 @@ fields. The resulting config will be available to your service through the nails
 module:
 
 ```js
-import nails from 'nails-boilerplate';
+import Nails from '@projectinvicta/nails';
 
 const service_config = nails.config
 ```
@@ -85,7 +86,7 @@ then `service_config.yourCustomField` as defined above will be equal to
 
 #### routes.js
 *routes.js* is a list defining mappings from a url path to a *Controller* and
-*Action*. Each entry in the list is an array with three elements:
+*Action*. Routes are now strongly typed (see `lib/config.ts` and `lib/Router.ts`). Each entry in the list is an array with three elements:
 `[method, path, options]`
 
 **method** is a string defining the HTTP request method of the route. Supported
@@ -134,15 +135,9 @@ parameters work.
 
 #### db.js
 
-Quickly configure your database connection here. Nails comes pre-configured to
-use the sequelize connector, giving your models sequelize support. The initial setup
-uses a *sqlite3* database file `config/development.db` and an in-memory database in the test environment. Change the address to change the location and
-version of your desired sql database. Check out [Sequelize](https://sequelize.org)
-for more info.
-
-Alternatively, you can configure a connection to MongoDB using the mongoose_connector.js.
-If enabled, models will accept [Mongoose](https://mongoosejs.com/docs/) schemas and will
-be backed by the desired MongoDB. Consider using the in-memory DB during development.
+Quickly configure your database connection here. The initial setup uses a *sqlite3* database file `config/development.db`
+and an in-memory database in the test environment. Change the address to change the location and
+version of your desired sql database. Check out [Sequelize](https://sequelize.org) for more info.
 
 ## Controller
 
@@ -153,10 +148,9 @@ actions, receiving **params**, **request**, and **response** as arguments.
 
 For Example:
 ``` js
-// const Controller = requre("nails-boilerplate").Controller
-import nails from 'nails-boilerplate';
+import { Controller } from '@projectinvicta/nails';
 
-class HomeController extends nails.Controller {
+class HomeController extends Controller {
   index(params, request, response) {
     // default action
   }
@@ -193,7 +187,9 @@ it will accept GET requests to /data instead. All local routes are
 implicitly routed to their respective parent controllers.
 
 ```js
-export default class UsersController extends nails.Controller {
+import { Controller } from '@projectinvicta/nails';
+
+export default class UsersController extends Controller {
   routes = [
     // Routes requests to /absolute/path
     ['get', '/absolute/path', {action: 'actionA'}],
@@ -280,12 +276,15 @@ You can configure an individual route to respond with JSON by setting the `json`
 ```
 
 ##### API Controllers
-By setting `json` to `true`, all actions in a controller will respond with JSON.
+By setting `json` to `true`, all actions in a controller will respond with JSON by default.
+This can be overridden for individual routes by setting `{json: false}` in the route options.
 
 ```js
-class YourApiController extends nails.Controller {
+import { Controller } from '@projectinvicta/nails';
+
+class YourApiController extends Controller {
   json = true;
-  
+
   action(params, request, response) {
     return {your: 'jsonresponse'};
   }
@@ -294,27 +293,28 @@ class YourApiController extends nails.Controller {
 
 ## Model
 
-Models are programmatic representations of data you wish to persist in a
-database. The constructor for Model accepts two arguments: the `modelName` and an
-`options` object which is passed to the database connector module.
+Models are programmatic representations of data you wish to persist in a database. Nails connects to
+your database of choice using the Sequelize ORM.
 
 ### Sequelize Models
 
 Sequelize models are subclasses of
 [Sequelize Models][sequelize_model_docs], and come with the `count()`, `findAll()`,
 and `create()` methods, to name a few. You can define your own models by
-extending an instance of the `Model` class provided by Nails:
+extending an instance of the `Model` class provided by Nails. Model files must export the Model subclass as a default export and a named `schema` export.
+They can also export an `options` object to provide ModelInitializationOptions as well as `defer`, `finalize`, and `migrate` functions.
 
 ```js
-// const Model = require("nails-boilerplate").Model;
-import nails from 'nails-boilerplate';
-import {DataTypes} from 'sequelize';
-schema = {
+import { Model, DataTypes } from '@projectinvicta/nails';
+
+// REQUIRED
+export const schema = {
   name: {type: DataTypes.STRING, allowNull: false},
   email: {type: DataTypes.STRING, allowNull: false}
 };
 
-options = {
+// Optional
+export const options = {
   indexes: [
     {
       unique: true,
@@ -323,38 +323,37 @@ options = {
   ],
 };
 
-export default class User extends new Model("User", {schema, options}) {
+// REQUIRED
+export default class User extends Model {
   someHelperMethod() {
     // This method will be available on all instances of User and is
     // an ideal way to simplify data manipulation.
   }
 };
 
-```
+// Optional
+export async function defer(models) {
+  // define associations here
+}
 
-### Mongoose Models
-Mongoose models are subclasses of
-[Mongoose Models][mongoose_model_docs], and come with the `save()`, `find()`,
-and `where()` methods, to name a few. You can define your own models by
-extending an instance of the `Model` class provided by Nails:
+// Optional
+export async function finalize(models) {
+  // any final model setup
+}
 
-``` js
-// const Model = require("nails-boilerplate").Model;
-import nails from 'nails-boilerplate';
-const userSchema = {name: String, email: String};
-export default class User extends new Model("User", {schema: userSchema}) {
-  // Define your helper methods here
-};
+// Optional
+export async function migrate(queryInterface) {
+  // migration logic
+}
 ```
 
-The `schema` option for Mongoose Models accepts a schema field that is used
-to define how documents are stored in MongoDB.
-
 ### Model Library
 Nails will store all instantialized models in a single object called `MODELS`. By accessing these models via the library, you can avoid circular dependencies and ensure all models have been fully initialized.
 
 ```js
-class User extends nails.Model("User", {schema, options}) {
+import Nails, { Model } from '@projectinvicta/nails';
+// ...
+class User extends Model {
   // A helper method which depends on anoher model using the
   // Nails Model Library rather than directly importing the model.
   async findFriends() {
@@ -364,18 +363,6 @@ class User extends nails.Model("User", {schema, options}) {
 ```
 This design pattern is not always necessary, but will help avoid circular dependencies.
 
-### Database Connectors
-
-Database connectors are intermediaries which define how a Model interacts with
-a database. Database connector modules need to export two methods:
-* _connect(db_config)_ uses the db config defined in *db.js* to connect to
-  a database. This function will be called once by Nails.
-* _generateModelSuperclass(name, options)_ uses the provided Model name and
-  options to generate a Model prototype for use as an interface. A Model
-  interface is generated for each of your models, allowing them to interact with
-  a database. Ideally, interfaces will define save() and find() methods, but
-  these methods and their implementations are up to the individual connector.
-
 ## View
 Views are dynamic templates used to render an html response for a browser.
 Nails comes prepackaged with EJS templates.
@@ -415,5 +402,4 @@ Enjoy! Feature requests, bug reports, and comments are welcome on github.
 
 [express_routing_docs]: https://expressjs.com/en/guide/routing.html
 [express_request_docs]: https://expressjs.com/en/5x/api.html#req
-[mongoose_model_docs]: https://mongoosejs.com/docs/api/model.html
 [sequelize_model_docs]: https://sequelize.org/docs/v6/core-concepts/model-basics/

package/bin/test/test_init.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+# Store the fully qualified location of the local nails module directory
+NAILS_MODULE_DIR=$(pwd)
+
+# Create a temporary directory for the test project with a datestring
+DATE_STRING=$(date +%Y%m%d%H%M%S)
+TEST_DIR="/tmp/test_project_$DATE_STRING"
+mkdir -p $TEST_DIR
+
+# Create a new nails project using the local version of nails-boilerplate
+npx $NAILS_MODULE_DIR/ init $TEST_DIR
+
+# Change directory to the test project
+cd $TEST_DIR
+
+# Link the local @projectinvicta/nails module
+npm link $NAILS_MODULE_DIR
+
+# Install other dependencies
+npm install
+
+# Run tests in the new test project
+npm test
+
+# Return to the original nails module directory
+cd $NAILS_MODULE_DIR
+
+# Unlink the local @projectinvicta/nails module
+npm unlink @projectinvicta/nails
+
+# Clean up the temporary directory
+rm -rf $TEST_DIR

package/index.ts

@@ -0,0 +1,11 @@
+import Nails from './lib/Nails.ts';
+import ControllerInternal from './lib/Controller.ts';
+
+export { DataTypes } from 'sequelize';
+
+export default Nails;
+
+export const Controller = ControllerInternal;
+export * from './lib/config.ts';
+
+export { Model } from 'sequelize';

package/lib/Controller.ts

@@ -0,0 +1,207 @@
+import { type Request, type Response } from 'express';
+import { type WebSocket } from 'ws';
+import { type RouteOptions, type RouteDefinition, type ControllerDoRouteParams } from './config.ts'; // Assuming RouteDefinition is exported from Config.ts
+
+// Define a basic Router interface based on its usage
+interface Router {
+  on(event: string, listener: Function): void;
+  removeAllListeners(event: string): void;
+  addRoutes(routes: RouteDefinition[]): void;
+}
+
+// Global router instance
+let router: Router;
+let controller_proto: Controller; // This will be assigned an instance of Controller
+
+// TODO: refactor error generation
+const NAME_REQUIRED_ERROR = (): Error => {
+  return new Error(
+      'FATAL ERROR::: Named function required for Controller constructor method');
+};
+
+const DISABLE_AUTORENDER = new (class DisableAutorender {});
+
+// The base controller definition
+class Controller {
+  // Static properties
+  static router: Router; // Static reference to the router
+  static models: Record<string, any>; // Static reference to models, assuming key-value pairs
+
+  static get DISABLE_AUTORENDER(): typeof DISABLE_AUTORENDER {
+    return DISABLE_AUTORENDER;
+  }
+
+  static setRouter(router_singleton: Router): void {
+    Controller.router = router = router_singleton;
+  }
+
+  static setModels(models: Record<string, any>): void {
+    Controller.prototype.models = models;
+  }
+
+  // Instance properties
+  models: Record<string, any>; // This will be assigned via Controller.setModels
+  routes: RouteDefinition[]; // Assuming routes are defined on subclasses
+  json: boolean;
+
+  constructor() {
+    const controllerName = this._getControllerName();
+    router.removeAllListeners('dispatchTo:' + controllerName);
+    router.on('dispatchTo:' + controllerName, this._do.bind(this));
+  }
+
+  _getControllerName(): string {
+    return this.constructor.name.toLowerCase().replace(/controller$/, '');
+  }
+
+  /** Initializes local and global routes defined on the Controller subclass */
+  _registerControllerRoutes(): void {
+    // `this.json` is not explicitly defined on Controller, but expected on subclasses
+    // assuming it's a boolean or undefined
+    const defaultToJson = this.json;
+    const controllerName = this._getControllerName();
+    if (this.routes && this.routes.length) {
+      const localizedRoutes: RouteDefinition[] = this.routes.map(route => {
+        // TODO: throw an error if :controller is present in local routes
+        // TODO: also account for other malformed local routes
+        const routePrefix = `/${controllerName}/`;
+        const modifiedDestination = (route[1][0] == '/')
+            ? route[1]
+            : (route[1].startsWith('./') ? route[1].replace('./', routePrefix) : routePrefix + route[1]);
+        const modifiedOptions: RouteOptions = {...route[2]};
+
+        if (!('json' in modifiedOptions)) modifiedOptions.json = defaultToJson;
+        if (!('action' in modifiedOptions)
+            && typeof modifiedDestination === 'string' && !modifiedDestination.includes(":action")
+            && !Object.values(modifiedOptions).includes('action')) {
+          const destinationParts = modifiedDestination.split("/");
+          modifiedOptions.action = destinationParts[destinationParts.length - 1];
+        }
+        modifiedOptions.controller = controllerName;
+        return [route[0], modifiedDestination, modifiedOptions];
+      });
+      router.addRoutes(localizedRoutes);
+    }
+  }
+
+  /****  Network Methods  *****/
+  /**
+   *  The main entry function of the controller.
+   *
+   *  @param {string} options.action      The action called for this controller
+   *  @param {object} options.params      The parameter hash for this action
+   *  @param {object} options.request     The http request object from the http server
+   *  @param {object} options.response    The http response object from the http server
+   *  @param {object} options.ws          The WebSocket instance
+   *  @param {object} options.next        The Express NextFunction
+   */
+  async _do({action, params, request, response, ws, next}: ControllerDoRouteParams): Promise<void> {
+    (request as any).handled_by_controller = true;
+    const doAction: Function = (this as any)[action]; // Action method on the controller
+
+    console.log(this.constructor.name, 'doing', action);
+
+    // TODO: let express handle errors
+    if (!doAction || typeof doAction !== 'function') {
+      const error = new Error('Action Not Available: #' + action);
+      if (response) {
+        response.status(404).send({
+          error: error.message + '\n' + error.stack
+        });
+        return;
+      }
+      if (ws) {
+        ws.close(1003, "Action Not available: #" + action);
+      }
+      return;
+    }
+
+    if (ws && !response) { // If it's a websocket request and not an http response
+      await doAction.call(this, params, ws, request);
+      return;
+    }
+
+    // Override async with Controller definition.
+    // Not using prototypal function objects
+    let actionResponse;
+    try {
+      actionResponse = await doAction.call(this, params, request, response);
+    } catch (e) {
+      // console.error(e);
+      return next(e);
+      // response.write({error: e.message, stack: e.stack});
+      // actionResponse = 500;
+    }
+        
+    if ((typeof actionResponse) == 'number') {
+      response.sendStatus(actionResponse);
+      return;
+    }
+
+    if (params._json) {
+      console.log("Sending JSON");
+      console.log("The ACTION RESPONSE", actionResponse);
+      response.json(actionResponse || {});
+      return;
+    }
+    //let viewAction = params._action ? params._action.toString() : "index";
+    let viewPath = `${this._getControllerName()}/${action}`;
+
+    const renderView = (templateVars: any): void => {
+      if (response.headersSent) {
+        return;
+      }
+      if (!!params._json) {
+        response.json(templateVars === undefined ? params : templateVars);
+        return;
+      }
+      response.render(
+        viewPath,
+        templateVars === undefined ? params : templateVars,
+        function(err: Error | null, html?: string) {
+          if (err && err.message.match(/Failed to lookup view/)) {
+            response.render(viewPath + ".ejs", params);
+          } else if (err) {
+            console.error(err);
+            response.sendStatus(400); // Changed from 400, err to just 400
+          } else {
+            response.send(html);
+          }
+        });
+    };
+
+    if (!response.headersSent
+        && !params._async
+        && actionResponse !== DISABLE_AUTORENDER) { // TODO: what does this do?
+      if (actionResponse instanceof Promise) {
+        // TODO: add a timeout so an unresolved promise doesn't preserve the
+        // connection indefinitely.
+        actionResponse
+          .then(renderView)
+          .catch((error: any) => {
+            console.error(error);
+            response.sendStatus(500); // Changed from 500, error to just 500
+          });
+      } else {
+        renderView(actionResponse);
+      }
+    }
+  }
+}
+
+const error_codes = [404, 500];
+error_codes.forEach((ec) => {
+  Controller.prototype[ec] = function (params: Record<string, any>, request: Request, response: Response): void {
+    //this._render('404');
+    console.error(ec.toString() + ' error with params', params);
+    const error = params['error'] || {};
+    const message = error.message || 'Error';
+    const stack_trace = error.stack || error || '';
+    response.setHeader('content-type', 'text/plain');
+    response.statusCode = ec;
+    response.end(message + '\n\n' + stack_trace);
+  };
+  (Controller.prototype as any)[ec.toString()] = Controller.prototype[ec];
+});
+
+export default Controller;