npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@awesomeeng/awesome-server

v1.6.2

Published

AwesomeServer is a customizable API Server framework for enterprise nodejs applications. It is an easy to setup HTTP or HTTPS or HTTP/2 server allowing you to provide flexible routing and controllers for responding to incoming requests in a consistent, re

Downloads

42

Readme

npm GitHub npm GitHub contributors GitHub last commit node GitHub issues Snyk Vulnerabilities for GitHub Repo David

AwesomeServer

AwesomeServer is a customizable API Server framework for enterprise nodejs applications. It is an easy to setup HTTP or HTTPS or HTTP/2 server allowing you to provide flexible routing and controllers for responding to incoming requests in a consistent, repeatable, performant fashion.

Features

AwesomeServer provides...

  • Easy to use.
  • HTTP support.
  • HTTPS support.
  • HTTP/2 support including push routing for preloading.
  • Or mix and match all three types of servers.
  • Basic routing to channel HTTP Method X along path Y into predefined functions.
  • Advanced routing using Controllers that takes your routing to the next level.
  • Controllers from classes, files, or whole directory trees.
  • Support for serving static files or whole directories to specific routes.
  • Easy built-in redirects.
  • Built around native promises and ready for async/await.
  • Integrated with AwesomeLog for easy logging if you want it.
  • Add your own custom servers beyond HTTP, HTTPS, or HTTP/2.

Why another API Server solution?

AwesomeServer is similar to Express, Fastly, Hapi, etc. and those are all good products. AwesomeServer just provides a different apporach to API Server code; one we think is cleaner and easier to use. If you want to use Express/Fastly/Hapi/whatever, that's perfectly fine by us. But if you want to try something a little cleaner, with less clutter, consider AwesomeServer.

Contents

Installation

Couldn't be easier.

npm install @awesomeeng/awesome-server

Setup

AwesomeServer is structured to allow you to create your servers, define your routes, and go.

Setup has five steps:

1). Require AwesomeServer...

const AwesomeServer = require("@awesomeeng/awesome-server");

2). Instantiate AwesomeServer...

let server = new AwesomeServer();

3). Add Servers...

server.addHTTPServer({
	hostname: "localhost",
	port: 7080
});

4). Add Routes...

server.route("GET","/test",(path,request,response)=>{
	return response.writeHTML("Hello world!");
});

5). Go!

server.start();

Servers

To use AwesomeServer you first have to add one (or more) servers to receive incoming requests. You can choose from HTTP, HTTPS or HTTP/2 servers, by default, or add your own custom server entirely.

HTTP Server

You create a HTTP Server instance with the addHTTPServer(config) method, as shown here:

let server = new AwesomeServer();
server.addHTTPServer({
	hostname: "localhost",
	port: 7080
});

HTTP Server functionally wraps the nodejs http module.

For more information on using HTTP Server with AwesomeServer, read the HTTP documentation.

HTTPS Server

You create a HTTPS Server instance with the addHTTPSServer(config) method, as shown here:

let server = new AwesomeServer();
server.addHTTPSServer({
	hostname: "localhost",
	port: 7080,
	cert: "./publickey.pem",
	key: "./privatekey.pem"
});

HTTPS Server functionally wraps the nodejs https module.

For more information on using HTTPS Server with AwesomeServer, read the HTTPS documentation.

HTTP/2 Server

You create a HTTP/2 Server instance with the addHTTP2Server(config) method, as shown here:

let server = new AwesomeServer();
server.addHTTP2Server({
	hostname: "localhost",
	port: 7080,
	cert: "./publickey.pem",
	key: "./privatekey.pem"
});

HTTP/2 Server functionally wraps the nodejs https module.

For more information on using HTTP/2 Server with AwesomeServer, read the HTTP/2 documentation.

Routing

Routing is the process of taking incoming requests from the servers and sending them to various handling functions or Controllers based on their method and path. Routing is primarily done by calling the server.route(method,path,handler) function, shown below...

server.route("GET","/test",someGetHandler);
server.route("POST","/test",somePostHandler);
server.route("*","*",catchAllHandler);

Each call to route take three arguments:

method: Is a valid HTTP Method or the wildcard "*" character. Methods are case-insemsitive.

path: Describes how to match against the path portion of the incoming request. The most basic type of path is an exact match which is a string without any wildcard characters such as /hello/world. There are several different types of paths and you can read all about the options in the Paths section below.

handler: May be one of several different things used to describe how to handle the incoming request that has matched the method and path conditions. The handler is only called if the method and path are matches. A handler must return a Promise.

See our detailed Routing documentation for a lot more details.

Handler Types

Handlers can be one of several different means of describing how to handle a request:

function: The most basic form of handling a route, a function passed in as a handler will be executed when the route matches. The function is executed with the signature (path,request,response).

server.route("GET","/test",function(path,request,response){
    return new Promise((resolve,reject)=>{
   	 ... do something ...
   	 resolve();
    });
});

If using a Positional Parameter Path, the signature of the handler function will be (params,request,response).

controller: You can pass a controller or controller class in as a handler. The controller will then be executed when the route matches. If a controller class is passed in, an instance of the controller is instantiated and used. Learn more about the awesomeness that is controllers in the Controllers section below.

let mycontroller = new MyController();
server.route("GET","/test",mycontroller);

filename: If you pass a filename to a valid existing .js file that exports a Controller instance or Controller class, AwesomeServer will require the Controller file, create an instance of that controller, if needed, and then use that as the handler as described above. This enables working with Controllers in a much easier way.

server.route("GET","/test","./MyController.js");

directory: If you pass a path to a valid existing directory, AwesomeServer will recursively walk the directory mapping any valid .js file that exports a Controller instance or Controller class. The mapping is based on the route passed in, the location of the controller file relative to the root directory name provided, and the filename itself. So if you had the following structure...

files/
  one.js
  two.js
  three.js
  three/
    four.js

and routed server.route("*","api","./files"); the resulting routes would be /api/one, /api/two, /api/three, and /api/three/four. One route for each matching .js file.

Paths

Most of the routing stuff above allows you to specify the path you want to match against. The value of path may be one of following...

  • A Exact path string:
/path
  • A Starts With path string:
/path*
  • An Ends With path string:
*/path
  • A Contains path string:
*path*
  • An Or Expression path string:
/path|/path*|*/path
  • a Positional Parameter Expression path string:
/path/:param
  • a Regular Expression:
^/path/
  • or a custom implementation of our AbstractPathMatcher class:
new AbstractPathMatcher() { ... }

To learn more about the details of Paths and Path Matching, check out our dedicated Paths Documentation.

Controllers

A controller is a special type of routing that allows you to keep logical API behaviour together in a unified class. Controllers respond to any HTTP method for a given path; so you can write a GET handler and a POST handler together in a single class focused around a given endpoint route. Controllers are roughly based on Rail/Grails and other frameworks, but with a little more JS magic.

A controller is always a Class (or instance of) that extends from AwesomeServer.AbstractContoller. AbstractController provides the handling of the incoming request and executing the appropriate method for the request based on the HTTP method.

In your subclass of AbstractController, you simply implement a method for one of the well used HTTP Methods (GET, POST, PUT, DELETE, HEAD, OPTIONS, CONNECT, TRACE, PATCH).

class MyController extends AbstractController {
	constructor() {
		super();
	}

	async get(path,request,response) {
		await response.writeText("Controller "+path);
	}

	async post(path,request,response) {
		await response.writeText("Controllers are awesome.");
	}
}

If the controller does not contain a corresponding method for the HTTP Method the controller will execute the any() function (see below).

You can read lots more about Controllers in our dedicated Controller Documentation.

Documentation

Examples

AwesomeServer ships with a set of examples for your reference.

  • BasicServer: An example of doing a basic HTTP server.

  • HTTPSServer: An example of doing a basic HTTPS server including adding a public certificate and a private key.

  • HTTP2Server: An example of doing a basic hTTP/2 server including how to push multiple responses for a single request.

  • BasicController: An example of implementing a basic controller and routing to it.

  • ControllerClasses: An example of implementing multiple controllers and routing with Controller File Routing.

  • ControllerDirectory: An example of using Controller Directory Routing with multiple controllers and sub-directories.

  • FileServer: How to build a basic File Server using Server Directory Routing.

  • HTTP2FileServer: An example of doing a slightly more complicated HTTP/2 server using Push Serve Routing and File Serve Routing fallback.

  • MultipleRoutes: An example of doing multiple routes for a single request and why route ordering is important.

  • PositionalParams: An example of using Positional Parameters Paths.

The Awesome Engineering Company

AwesomeServer is written and maintained by The Awesome Engineering Company. We belive in building clean, configurable, creative software for engineers and architects and customers.

To learn more about The Awesome Engineering Company and our suite of products, visit us on the web at https://awesomeeng.com.

Support and Help

This product is maintained and supported by The Awesome Engineering Company. For support please file an issue or contact us via our Webiste at https://awesomeeng.com. We will do our best to respond to you in a timely fashion.

License

AwesomeServer is released under the MIT License. Please read the LICENSE file for details.