@projectinvicta/nails 2.0.15 → 3.0.0

package/templates/default/public/README.xml

@@ -1,57 +1,48 @@
-<h1 id="nailsboilerplateanodewebserviceframework">Nails-Boilerplate: A Node Webservice Framework</h1>
-<p>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.</p>
-<p>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.</p>
-<h2 id="install">Install</h2>
-<pre><code>sudo npm install -g nails-boilerplate
+<h1 id="nailsanodewebserviceframework">Nails: A Node Webservice Framework</h1>
+<p>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.</p>
+<p>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.</p>
+<h2 id="gettingstarted">Getting Started</h2>
+<p>There are two recommended ways to get started with Nails.</p>
+<h3 id="usingnpxrecommended">Using NPX (Recommended)</h3>
+<p>You can create a new Nails project without a global installation using <code>npx</code>:</p>
+<pre><code class="bash language-bash">npx @projectinvicta/nails init &lt;app_name&gt;
+</code></pre>
+<h3 id="usingglobalinstall">Using Global Install</h3>
+<p>Alternatively, you can install the package globally:</p>
+<pre><code class="bash language-bash">npm install -g @projectinvicta/nails
 
 nails init &lt;app_name&gt;
 </code></pre>
-<p>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.</p>
-<pre><code>cd app_name
-
+<p>After initializing your app, navigate into the new directory and start the server:</p>
+<pre><code class="bash language-bash">cd &lt;app_name&gt;
 npm install
-
 npm start
 </code></pre>
 <h2 id="gettingtoknowyournailsservice">Getting to know your Nails service</h2>
 <p>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.</p>
-<h3 id="config">Config</h3>
-<p>Your configuration files are stored in app_name/config/. There are three default config files:</p>
-<pre><code>service.js
-routes.js
-db.js
+<h3 id="namedexports">Named Exports</h3>
+<p><code>nails</code> now provides a number of useful named exports. You can import them as follows:</p>
+<pre><code class="js language-js">import Nails, { Controller, Model, DataTypes, /* config types */ } from '@projectinvicta/nails';
 </code></pre>
+<h3 id="config">Config</h3>
+<p>Your configuration files are stored in app_name/config/.</p>
 <p>Each default config file is annotated with comments documenting each field to
 help you tailor your service to your needs.</p>
 <h4 id="servicejs">service.js</h4>
 <p>service.js contains information necessary to run your server. By default, it
-specifies the port and the location of important libraries. To override these
-values in different runtime environments, add a child object.</p>
+specifies the port and the location of important libraries.</p>
 <pre><code class="js language-js">export default {
   ...
-  PORT: 3000,
-  PROD: {
-    PORT: 80
-  }
+  SERVER_ROOT: "/path/to/my/nails/service",
+  PORT: 3333,
+  SSL_PORT: 3334,
 }
 </code></pre>
-<p>Nails checks the NODE<em>ENV environment variable. If a matching child config
-object is present, then those values will override the parent config. In the
-above example, PORT will be overridden to 80 if NODE</em>ENV is set to PROD.</p>
 <p>While most of these values don't need to be changed, feel free to add custom
 fields. The resulting config will be available to your service through the nails
 module:</p>
-<pre><code class="js language-js">import nails from 'nails-boilerplate';
+<pre><code class="js language-js">import Nails from '@projectinvicta/nails';
 
 const service_config = nails.config
 </code></pre>
@@ -66,7 +57,7 @@ const service_config = nails.config
 <code>'yourCustomValue'</code>.</p>
 <h4 id="routesjs">routes.js</h4>
 <p><em>routes.js</em> is a list defining mappings from a url path to a <em>Controller</em> and
-<em>Action</em>. Each entry in the list is an array with three elements:
+<em>Action</em>. Routes are now strongly typed (see <code>lib/config.ts</code> and <code>lib/Router.ts</code>). Each entry in the list is an array with three elements:
 <code>[method, path, options]</code></p>
 <p><strong>method</strong> is a string defining the HTTP request method of the route. Supported
 methods are <em>GET</em>, <em>PUT</em>, <em>POST</em>, <em>DELETE</em>, and <em>ALL</em>. All is a special case
@@ -109,24 +100,18 @@ than indices. You can name your regex captures "controller" and/or "action"
 to dynamically route your request to the appropriate handler.</li>
 </ul>
 <h4 id="dbjs">db.js</h4>
-<p>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 <em>sqlite3</em> database file <code>config/development.db</code> 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 <a href="https://sequelize.org">Sequelize</a>
-for more info.</p>
-<p>Alternatively, you can configure a connection to MongoDB using the mongoose_connector.js.
-If enabled, models will accept <a href="https://mongoosejs.com/docs/">Mongoose</a> schemas and will
-be backed by the desired MongoDB. Consider using the in-memory DB during development.</p>
+<p>Quickly configure your database connection here. The initial setup uses a <em>sqlite3</em> database file <code>config/development.db</code>
+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 <a href="https://sequelize.org">Sequelize</a> for more info.</p>
 <h2 id="controller">Controller</h2>
 <p>Controllers are defined in app/controllers/. Each controller module should
 define a Controller subclass. The name will be used to match routes defined in
 config/routes.js for incoming requests. Methods on the controller can be used as
 actions, receiving <strong>params</strong>, <strong>request</strong>, and <strong>response</strong> as arguments.</p>
 <p>For Example:</p>
-<pre><code class="js language-js">// const Controller = requre("nails-boilerplate").Controller
-import nails from 'nails-boilerplate';
+<pre><code class="js language-js">import { Controller } from '@projectinvicta/nails';
 
-class HomeController extends nails.Controller {
+class HomeController extends Controller {
   index(params, request, response) {
     // default action
   }
@@ -154,7 +139,9 @@ object returned by the getData function. If the route is changed to:</p>
 <p><code>["get", "/data", {action: 'getData', json: true}],</code></p>
 <p>it will accept GET requests to /data instead. All local routes are
 implicitly routed to their respective parent controllers.</p>
-<pre><code class="js language-js">export default class UsersController extends nails.Controller {
+<pre><code class="js language-js">import { Controller } from '@projectinvicta/nails';
+
+export default class UsersController extends Controller {
   routes = [
     // Routes requests to /absolute/path
     ['get', '/absolute/path', {action: 'actionA'}],
@@ -226,8 +213,11 @@ overridden to allow for the rendering of views by name.</p>
 <pre><code class="js language-js">['get', '/your/json/route', {json: true}],
 </code></pre>
 <h5 id="apicontrollers">API Controllers</h5>
-<p>By setting <code>json</code> to <code>true</code>, all actions in a controller will respond with JSON.</p>
-<pre><code class="js language-js">class YourApiController extends nails.Controller {
+<p>By setting <code>json</code> to <code>true</code>, all actions in a controller will respond with JSON by default.
+This can be overridden for individual routes by setting <code>{json: false}</code> in the route options.</p>
+<pre><code class="js language-js">import { Controller } from '@projectinvicta/nails';
+
+class YourApiController extends Controller {
   json = true;
 
   action(params, request, response) {
@@ -236,23 +226,24 @@ overridden to allow for the rendering of views by name.</p>
 }
 </code></pre>
 <h2 id="model">Model</h2>
-<p>Models are programmatic representations of data you wish to persist in a
-database. The constructor for Model accepts two arguments: the <code>modelName</code> and an
-<code>options</code> object which is passed to the database connector module.</p>
+<p>Models are programmatic representations of data you wish to persist in a database. Nails connects to
+your database of choice using the Sequelize ORM.</p>
 <h3 id="sequelizemodels">Sequelize Models</h3>
 <p>Sequelize models are subclasses of
 <a href="https://sequelize.org/docs/v6/core-concepts/model-basics/">Sequelize Models</a>, and come with the <code>count()</code>, <code>findAll()</code>,
 and <code>create()</code> methods, to name a few. You can define your own models by
-extending an instance of the <code>Model</code> class provided by Nails:</p>
-<pre><code class="js language-js">// const Model = require("nails-boilerplate").Model;
-import nails from 'nails-boilerplate';
-import {DataTypes} from 'sequelize';
-schema = {
+extending an instance of the <code>Model</code> class provided by Nails. Model files must export the Model subclass as a default export and a named <code>schema</code> export.
+They can also export an <code>options</code> object to provide ModelInitializationOptions as well as <code>defer</code>, <code>finalize</code>, and <code>migrate</code> functions.</p>
+<pre><code class="js language-js">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,
@@ -261,30 +252,34 @@ 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
+}
+
+// Optional
+export async function finalize(models) {
+  // any final model setup
+}
+
+// Optional
+export async function migrate(queryInterface) {
+  // migration logic
+}
 </code></pre>
-<h3 id="mongoosemodels">Mongoose Models</h3>
-<p>Mongoose models are subclasses of
-<a href="https://mongoosejs.com/docs/api/model.html">Mongoose Models</a>, and come with the <code>save()</code>, <code>find()</code>,
-and <code>where()</code> methods, to name a few. You can define your own models by
-extending an instance of the <code>Model</code> class provided by Nails:</p>
-<pre><code class="js language-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
-};
-</code></pre>
-<p>The <code>schema</code> option for Mongoose Models accepts a schema field that is used
-to define how documents are stored in MongoDB.</p>
 <h3 id="modellibrary">Model Library</h3>
 <p>Nails will store all instantialized models in a single object called <code>MODELS</code>. By accessing these models via the library, you can avoid circular dependencies and ensure all models have been fully initialized.</p>
-<pre><code class="js language-js">class User extends nails.Model("User", {schema, options}) {
+<pre><code class="js language-js">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() {
@@ -293,18 +288,6 @@ to define how documents are stored in MongoDB.</p>
 }
 </code></pre>
 <p>This design pattern is not always necessary, but will help avoid circular dependencies.</p>
-<h3 id="databaseconnectors">Database Connectors</h3>
-<p>Database connectors are intermediaries which define how a Model interacts with
-a database. Database connector modules need to export two methods:</p>
-<ul>
-<li><em>connect(db</em>config)_ uses the db config defined in <em>db.js</em> to connect to
-a database. This function will be called once by Nails.</li>
-<li><em>generateModelSuperclass(name, options)</em> 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.</li>
-</ul>
 <h2 id="view">View</h2>
 <p>Views are dynamic templates used to render an html response for a browser.
 Nails comes prepackaged with EJS templates.

package/templates/default/server/controllers/home_controller.js

@@ -1,6 +1,6 @@
-import nails from "nails-boilerplate";
+import {Controller} from "@projectinvicta/nails";
 
-export default class HomeController extends nails.Controller {
+export default class HomeController extends Controller {
   /**
    * You can define a local routing table directly in the controller.
    * Local routes take precidence over global routes. All local routes

package/templates/{server/controllers/home_controller.js → default/server/controllers/users_controller.ts}

@@ -1,34 +1,29 @@
-import nails from "nails-boilerplate";
-
-export default class HomeController extends nails.Controller {
-  /**
-   * You can define a local routing table directly in the controller.
-   * Local routes take precidence over global routes. All local routes
-   * are prefixed with the controller name unless they start with '/'.
-   * For example, in HomeController the following route:
-   * 
-   *   ["get", "data", {action: 'getData', json: true}],
-   * 
-   * will accept GET requests to /home/data and respond with the json
-   * object returned by the getData function. If the route is changed to:
-   * 
-   *   ["get", "/data", {action: 'getData', json: true}],
-   * 
-   * it will accept GET requests to /data instead. All local routes are
-   * implicitly routed to their respective parent controllers.
-   */
-  routes = [
-    ["get", "data", {action: 'getData', json: true}],
-  ];
-
-  index(params, request, response) {
-    return {
-      title: "My first Nails Service",
-      welcome_message: "Welcome to Nails"
-    };
-  }
-
-  getData(params, request, response) {
-    return {testData: Math.floor(Math.random() * 10000000)}
-  }
-};
+import {Controller} from "@projectinvicta/nails";
+import User from "../models/User";
+
+export default class UsersController extends Controller {
+  /**
+   * You can define a local routing table directly in the controller.
+   * Local routes take precidence over global routes. All local routes
+   * are prefixed with the controller name unless they start with '/'.
+   * For example, in HomeController the following route:
+   * 
+   *   ["get", "data", {action: 'getData', json: true}],
+   * 
+   * will accept GET requests to /home/data and respond with the json
+   * object returned by the getData function. If the route is changed to:
+   * 
+   *   ["get", "/data", {action: 'getData', json: true}],
+   * 
+   * it will accept GET requests to /data instead. All local routes are
+   * implicitly routed to their respective parent controllers.
+   */
+  routes = [
+    ["get", "./list"],
+  ];
+
+  async list(params, request, response) {
+    return await User.findAll();
+  }
+
+};

package/templates/default/server/models/Dog.ts

@@ -0,0 +1,8 @@
+import {Model, DataTypes} from "@projectinvicta/nails";
+
+export const schema = {
+  good: DataTypes.BOOLEAN,
+  name: DataTypes.STRING,
+};
+
+export default class Dog extends Model {};

package/templates/default/server/models/User.ts

@@ -0,0 +1,14 @@
+import {Model, DataTypes} from "@projectinvicta/nails";
+import Dog from "./Dog";
+
+export const schema = {
+  name: DataTypes.STRING,
+  verified: DataTypes.BOOLEAN,
+  email: DataTypes.STRING,
+}
+
+export default class User extends Model {};
+
+export async function defer() {
+  await User.hasMany(Dog);
+}

package/templates/default/spec/User.test.js

@@ -1,19 +1,21 @@
-import nails from "nails-boilerplate";
-import service_config from '../config/service.js';
+import Nails from "@projectinvicta/nails";
+import User from "#models/User";
+import service_config from '#config/service.js';
 import { beforeAll, test, expect } from "vitest";
 
 const TEST_USER_EMAIL = "test@test.com";
 const TEST_USER_NAME = "JohnDoe";
 beforeAll(async () => {
   // Only initialize the Models.
-  await nails.MODELS.init( service_config );
+  await new Nails(service_config).configure();
+  // await nails.MODELS.init( service_config );
 });
 
 test("Can create a User", async () => {
-  const user = await nails.MODELS.User.create({name: TEST_USER_NAME, email: TEST_USER_EMAIL});
+  const user = await User.create({name: TEST_USER_NAME, email: TEST_USER_EMAIL});
 
   expect(user.id).toBeDefined();
-  const retrievedUser = await nails.MODELS.User.findByPk(user.id);
+  const retrievedUser = await User.findByPk(user.id);
   expect(retrievedUser.id).toBeDefined();
   expect(retrievedUser.name).toEqual(TEST_USER_NAME);
   expect(retrievedUser.email).toEqual(TEST_USER_EMAIL);

package/templates/default/spec/home_controller.test.js

@@ -1,4 +1,4 @@
-import nails from 'nails-boilerplate';
+import Nails from "@projectinvicta/nails";
 // import chai from 'chai';
 import {default as chaiHttp, request} from 'chai-http';
 import service_config from '../config/service.js';
@@ -8,8 +8,8 @@ let express_app;
 
 beforeAll(async () => {
   // Initialize the application and start the server
-  (await nails( service_config )).startServer();
-  express_app = nails.application;
+  await new Nails( service_config ).startServer();
+  express_app = Nails.application;
   chai.use(chaiHttp);
   chai.should();
 })

package/index.js

@@ -1,6 +0,0 @@
-// Sets the Nails global object
-import nails from './lib/nails.js';
-
-export default nails;
-
-// set up Nails here

package/lib/collection.js

@@ -1,6 +0,0 @@
-/**
- * The collection is an object descending from the array class.
- * It comes with methods for persising groups of models to the database.
- */
-export default function Collection() {
-}

package/lib/controller.js

@@ -1,182 +0,0 @@
-// const fs = require('fs');
-import fs from 'node:fs';
-import events from 'node:events';
-// const events = require('events');
-import application from './application.js';
-// const application = require('./application');
-
-var router;
-var controller_proto;
-var models;
-
-// TODO: refractor error generation
-var NAME_REQUIRED_ERROR = function () {
-  return new Error(
-      'FATAL ERROR::: Named function required for Controller constructor method');
-}
-
-const DISABLE_AUTORENDER = new (class DisableAutorender {});
-
-// The base controller definition
-class Controller {
-  constructor() {
-    var subclassName = this.constructor.name;
-    var controllerName = this._getControllerName();
-        // subclassName.toLowerCase().replace(/controller$/, '');
-    router.removeAllListeners('dispatchTo:' + controllerName);
-    router.on('dispatchTo:' + controllerName, this._do.bind(this));
-  }
-
-  static get DISABLE_AUTORENDER() {
-    return DISABLE_AUTORENDER;
-  }
-
-  static setRouter (router_singleton) {
-    Controller.router = router = router_singleton;
-  }
-
-  static setModels (models) {
-    Controller.prototype.models = models;
-  }
-
-  static extend (constructor) {
-    console.log('extending', constructor.name);
-    if (!constructor.name) throw NAME_REQUIRED_ERROR();
-    controller_proto = controller_proto || new Controller();
-    constructor.prototype.__proto__ = controller_proto;
-    var constructed = new constructor();
-
-    // configure event listeners on router.
-    var controller_name =
-        constructor.name.toLowerCase().replace(/controller$/, '');
-    router.removeAllListeners('dispatchTo:' + controller_name);
-    router.on('dispatchTo:' + controller_name, constructed._do.bind(constructed));
-
-    return constructed;
-  }
-
-  _getControllerName() {
-    return this.constructor.name.toLowerCase().replace(/controller$/, '');
-  }
-
-  /** Initializes local and global routes defined on the Controller subclass */
-  _registerControllerRoutes() {
-    const defaultToJson = !!this.json;
-    const controllerName = this._getControllerName();
-    if (this.routes && this.routes.length) {
-      const localizedRoutes = 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 = {...route[2]};
-        // TODO: introduce a shorthand so action doesn't have to be redefined everywhere
-        if (!('json' in modifiedOptions)) modifiedOptions.json = defaultToJson;
-        if (!('action' in modifiedOptions)
-            && !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} action      The action called for this controller
-   *  @param {object} params     The parameter hash for this action
-   *  @param {object} request     The http request object from the http server
-   *  @param {object} response    The http response object from the http server
-   *  @param {object} ws          The WebSocket instance
-   */
-  _do (action, params, request, response, ws) {
-    request.handled_by_controller = true;
-    var doAction = this[action];
-    console.log(this.constructor.name, 'doing', action);
-    // TODO: let express handle errors
-    if (typeof doAction != 'function') {
-      //return this['404'](params, request, response);
-      var error = new Error('Action Not Available: #' + action);
-      if (response) {
-        return response.status(404).send({
-          error: error.stack
-        });
-      }
-      return ws.close(1003, "Action Not available: #" + action);
-    }
-    if (ws && !response) {
-      return doAction.call(this, params, ws, request);
-    }
-    // Override async with Controller definition.
-    if (doAction.async != undefined) params._async = !!doAction.async;
-    let actionResponse = doAction.call(this, params, request, response);
-    let controller = params._controller.toString();
-    //let viewAction = params._action ? params._action.toString() : "index";
-    let viewPath = `${controller}/${action}`;
-    function renderView(templateVars) {
-      if (response.headersSent) {
-        return;
-      }
-      if (!!params._json) {
-        response.json(templateVars == undefined ? params : templateVars);
-        return;
-      }
-      response.render(
-        viewPath,
-        templateVars == undefined ? params : templateVars,
-        function(err, html) {
-          if (err && err.message.match(/Failed to lookup view/)) {
-            response.render(viewPath + ".ejs", params);
-          } else if (err) {
-            console.error(err);
-            response.sendStatus(400, err);
-          } else {
-            response.send(html);
-          }
-        });
-    }
-    // Default to the jsx engine. If that doesn't work, try the configured view engine.
-    if (!response.headersSent
-        && !params._async
-        && actionResponse != DISABLE_AUTORENDER) {
-      if (actionResponse instanceof Promise) {
-        // TODO: add a timeout so an unresolved promise doesn't preserve the
-        // connection indefinitely.
-        actionResponse
-          .then(renderView)
-          .catch(error => {
-            // TODO: only do one of these
-            console.error(error);
-            console.log(error);
-            response.sendStatus(500, error);
-          });
-      } else renderView(actionResponse);
-    }
-  }
-}
-
-const error_codes = [404, 500];
-error_codes.forEach((ec) => {
-  Controller.prototype[ec] = function (params, request, response) {
-    //this._render('404');
-    console.error(ec.toString() + ' error with params', params);
-    var error = params['error'] || {};
-    var message = error.message || 'Error';
-    var stack_trace = error.stack || error || '';
-    response.setHeader('content-type', 'text/plain');
-    response.statusCode = ec;
-    response.end(message + '\n\n' + stack_trace);
-  };
-  Controller.prototype[ec.toString()] = Controller.prototype[ec];
-
-});
-
-export default Controller;

package/lib/database_connector.js

@@ -1,12 +0,0 @@
-export default class DbConnector {
-  async connect() {
-    throw 'DbConnector#connect not implemented'
-  }
-  generateModelSuperclass() {
-    throw 'GenerateModelSuperclass not implemented'
-  }
-  
-  async afterInitialization() {
-    console.warn("DbConnector#afterInitialization not implemented");
-  }
-}