gosling

Gosling

Gosling is simple, plugin ready es6 node server similar to express.

Basic Use

import Gosling from 'gosling';

const app = new Gosling(1337);
app.listen();

app.use('/', () => (request, response, next) => {
    response.write('Hello World!');
    next();
});

HTTPS

HTTPS can be used out of the box with Gosling. Pass a node https options object to the constructor.

Note: HTTPS Options should either be the first or second argument, if second we assume Port is the first.

import { readFileSync } from 'fs';
import Gosling from 'gosling';

const httpsOptions = {
  key: readFileSync('./ssl/key.pem'),
  cert: readFileSync('./ssl/cert.pem')
};

const app = new Gosling(1337, httpsOptions);

app.listen();

Router

Gosling ships with a router bundled, it can be accessed by importing separately

import Gosling, { Router } from 'gosling';

const app = new Gosling(1337);
const router = new Router();

app.listen();

router.use('/', () => (req, res, next) => {});
app.use('/api', router);

When assigning a path to router that router is then scoped to only process request that match the prefix.

Routers are completely recursive and can be nested deeply.

import { Router } from 'gosling';

const router = new Router();
const subrouter = new Router();

subrouter.get(/\/post\/[a-z0-9]+$/, bobsLawBlog);
router.use('/api/blog', subrouter);

export router;

In Depth Use

Gosling's constructor takes the following optional arguments:

• port (Number);
• HTTPS Options (Object);
• middleware (as Request Objects);

Full API

Once instantiated Gosling offers the following methods:

• listen

  • Starts server.
  • Arguments:
    • port (Number) - throws error if port is already assigned
    • callback (Function)

• close

  • Stops server
  • Arguments:
    • callback (Function)

• port

  • Sets port if not set through constructor
  • Throws error if port is already assigned.
  • Getter / Setter

• use (Universal request)

  • Universal Request (runs for all requests)
  • Arguments:
    • Path [optional] String or RegExp
    • Thunk

• get

  • Only GET Requests
  • Arguments:
    • Path [optional] String or RegExp
    • Thunk

• post

  • Only POST Requests
  • Arguments:
    • Path [optional] String or RegExp
    • Thunk

• put

  • Only PUT Requests
  • Arguments:
    • Path [optional] String or RegExp
    • Thunk

• delete

  • Only DELETE Requests
  • Arguments:
    • Path [optional] String or RegExp
    • Thunk

Methods API in depth

The methods (get, post, put, delete, use) API takes two arguments and creates Request Objects… - Path (as String or RegExp) [optional] - Thunk (function returning function) [required] - Note: All method calls are chainable app.use().get().post() is valid.

Request Objects

Request Objects are the heart of Gosling's speed and simplicity. They can be hand coded or passed through the method API reducer.

// Request Object
{
    path: '/' /* String or RegExp */
    method: /GET/i /* RegExp only */
    thunk() {
        /* some code */
        return (request, response, next) => {
            /* response or request modifications */
            next();
        }
    }
}

Sample Usage

You can use the simple API to produce Request Objects by:

app.use('<Path>', () => (req, res, next) => {});
app.get('<Path>', () => (req, res, next) => {});
app.post('<Path>', () => (req, res, next) => {});
app.put('<Path>', () => (req, res, next) => {});
app.delete('<Path>', () => (req, res, next) => {});

Notes

• the methods API does the work of Method checking, so no need to pass that.
• the use method will try to run on every request.
• if no path is passed in, the thunk is processed on all matching request methods.
  • app.use(() => (req, res, next) => {}) will be run on all requests.
• All method calls are chainable
  • app.use(() => {}).get(() => {}).post(() => {});

Changelog

[3.0.0] - 2016-11-17

Added

• Support for adding multiple thunks to a statement
  • IE: app.use('/', thunk, thunk, thunk)
• Added comments to a lot of the code based
• Reorganized code so index.js is only the basic code, and utils.js contains all of our additional functions
• Added tests for outlier functionality.
• Modified error messages to be more specific to the problem that occurred.