jups v0.1.4

jups

A fast, lightweight web framework for NodeJS.

Why

There are many different web frameworks for NodeJS, with some of them more extensive and some more minimal. This is more of a side project that I designed to see if I could use it in REST APIs in the future for personal projects. It is designed in an extension-forward way, meaning that the main framework has no dependencies and is minimal in functionality, but is easily extensible with middleware/Object manipulation.

Features

• ZERO dependencies!
• Very fast (similar to Express).
• Written in Typescript.
  • Built-in .d.ts files.
  • Built with strict type checking.
• In-depth routing.
  • Supports Regex, strings and combined Regex + strings (e.g '/(home|h)/:name/hello').
  • Route variable support WITH optional variables.
  • Note, routing with only Regex nullifies route variables.
• Support for middleware.
• Support for subapps for easy route organisation (comparable to the router in Express).
• Async/await support.

Installation

npm i jups

Usage

const jups = require('jups');

jups()
    .use((req, res, next) => {
        res.write('Hello');
        next();
    })
    .get('/', (req, res) => {
        res.end(', world!');
    })
    .listen(3000);

For Typescript just use the following import syntax.

import jups from 'jups';

API

Table of Contents

• jups (function)
• Jups (class)
  • Variables
  • Methods
• Request (class)
  • Variables
  • Methods
• Response (class)
  • Variables
  • Methods
• JupsOptions (interface)
  • Members
• Route (interface)
  • Members
• Variable (interface)
  • Members
• SubApp (interface)
  • Members
• Middleware (interface)
  • Members
• Method (type)
  • Values

Jups Function

jups(options)

The default export of jups. It is basically a wrapper of the constructor for the Jups class.

• options -> JupsOptions\ The options to pass to the Jups constructor.

This function returns an instance of Jups.

Jups Class

jups.Jups(options)

The main class for the package which allows the framework to function.

• options -> JupsOptions\ The options for the class to use.

Jups Class Variables

• routes -> Route[]\ An array of routes that the instance is listening on.

• subApps -> SubApp[]\ An array of subapps that the instance has attached to it.

• middlewares -> Middleware[]\ An array of middleware that the instance has initialised.

• _otherwise -> Function\ The route that will be called when there are no other routes found.

• _error -> OptionalFunction\ The route that will be called when an error occurs in routes/middleware.

Jups Class Methods

¶ route(method, route, callback)

• method -> Method\ The method for the route. Will only call the callback whenever it matches the method.
• route -> string | RegExp\ The route to match for it to call the callback. Can be either a string '/home', a regex /(home|h)/ or a mixture of string and regex '/(home|h)'.
• callback -> Function\ The function for it to call when it matches. Needs to include Request and Response parameters.

This method will add a route endpoint handler to the client.

There can be multiple handlers per endpoint as long as the preceding handlers do not end the response. The route handling is converted to custom regex which then gets checked for matches.

As with most web frameworks, there can be variables within the routes (though currently this is only supported with string routes).

Also, there can also be optional parameters within the route at any point.

This function will return the Jups instance to allow chaining.

¶ use(base, ...uses)

• base -> string | RegExp | Jups | Function\ This is the route that has to match for this middleware/subapp to apply. For example, if given '/players', it would only match routes beginning with /players. Note, this can also just be middleware/a subapp which would default the base to /.
• uses -> Array\<Jups | Function>\ As many middleware/subapps that you want to apply to this base. You can also mix middleware/subapps if you please.

Tells the instance to use middleware or subapps. Subapps provide an easy way to organise your code. Middleware is called before routes and are usually used to fire the same piece of code for multiple routes following a specific base endpoint.

This function will return the Jups instance to allow chaining.

¶ otherwise(callback)

• callback -> Function\ The callback function that will be called if no other routes were matched.

This method is used for defining a function to be used for the otherwise route AKA the 404 route.

Simply put, this function ill be called if no other routes match the request.

This function will return the Jups instance to allow chaining.

¶ error(callback)

• callback -> Function\ The callback function that will be called if there were errors.

This method is used for defining a function to be used incase errors occur during the route listener.

For example if there is an error in the code for a route, this error handler will be called.

Note, this does not catch every single error in your code.

This function will return the Jups instance to allow chaining.

¶ listen(port = 80, httpsPort = 443)

• port -> number\ The port to run the app on. Defaults to port 80.
• httpsPort -> number\ The port to run the app on for SSL/HTTPS. Only needed if using SSL. Defaults to port 443.

This method is for initiating the app to listen for connections. Basically it starts up the server. If you are using SSL, you want to pass it an httpsPort if you do not want to use port 443. This method should be called AFTER defining all of your routes, subapps, and middleware.

This function will return the Jups instance to allow chaining.

Request

jups.Request()

This is the request class that will get sent with every request that the server will get. It is an extension of the IncomingMessage class that Node HTTP library uses by default with servers with new variables to make it cleaner to work with for Jups.

Request Variables

• params -> Object\ The URL parameters that got parsed. For example, in the route of /home/:name, there would be a parameter of name in params. If the URL was /home/isaac, the params object would have params.name which would be equal to isaac.
• query -> Object\ The URL query parameters from the request. For example, in this URL https://isaacoram.ca/?id=testing&name=isaac, the query parameters are ?id=testing&name=isaac which will get parsed into query.id and query.name.
• middlewares -> Middleware[]\ All of the middleware that the URL matched and the request will fire before calling the routes.
• routes -> Route[]\ All of the routes that the URL matched and the request will fire after calling all of the middleware.
• routeErrorHandler -> OptionalFunction\ The error callback that will be called if there are any errors that occur. For example, if a function returns an error in a route.

Response

jups.Response()

The response object that will be used to send the connection some data. This class extends the ServerResponse class that Node HTTP library uses by default with servers with new methods and variables to make it cleaner to work with for Jups.

Response Variables

• instantiated -> boolean\ Whether or not the response has been instantiated by otherwise or error callbacks.

Response Methods

¶ status(code, message)

• code -> number\ The HTTP status code to send to the connection.
• message -> Optionalstring\ An optional message that will be used alongside the status code. If not given, it will use the default message given by the status code.

A helper function to modify the status code that the server will send the connection.

This function can throw an error if the status code is invalid.

This function will return the Response instance to allow chaining.

JupsOptions

jups.JupsOptions{}

The options that can be passed to the Jups class in the constructor.

JupsOptions Members

• noOtherwise -> Optionalboolean\ Remove the default otherwise route for the instance.

• noErrorHandler -> Optionalboolean\ Remove the default error handling route for the instance.

• ssl -> Optional[SSLOptions]\ The SSL options if you want to run the server on HTTPS/SSL.

SSLOptions

jups.SSLOptions{}

These options are an extention to the options that are allowed to be passed to https.createServer. See here for more information. Below are the added members to the aforementioned options.

SSLOptions Members

• redirect -> Optionalboolean\ If you want the server to automatically redirect connections to the HTTPS version.

Route

jups.Route{}

A stored route in the Jups instance that contains information to match it and call the callback associated.

Route Members

• route -> string | RegExp\ The original given route to match.
• regex -> RegExp\ This is either the built regex based on the string given, or the original regex given.
• variables -> Optional[Variable[]]\ The route variables (ones prefixed with a colon).
• method -> Method\ The method that the route should match to be able to fire.
• callback -> Function\ The actual function that the route fires if the method and regex match.

Variable

jups.Variable{}

All the information stored about a Route variable.

Variable Members

• index -> number\ The path index that the variable is located (at which slash).
• name -> string\ The name of the variable (whatever followed the colon).
• optional -> boolean\ Whether or not the variable is optional (if the variable was followed by a question mark).

SubApp

jups.SubApp{}

A subapp enables easy organisation of routes by being able to split up specific groups of routes. This is pretty much the Jups class except it just stores routes within it without calling the listen method.

SubApp Members

• base -> string | RegExp\ The original given route for the subapp.
• regex -> RegExp\ The compiled Regex from the base. If the base is Regex, this will match it.
• variables -> Optional[Variable[]]\ The compiled variables for the subapp if any is needed.
• app -> Jups\ The Jups instance of the subapp.

Middleware

jups.Middleware{}

Middleware are simply functions that fire before any of the route callbacks fire. This creates the ability to provide functionality to a bunch of routes without having to implement it in each route callback. Middleware implements the same routing feature as routes.

Middleware Members

• route -> string | RegExp\ The original given route to match.
• regex -> RegExp\ This is either the built regex based on the string given, or the original regex given.
• variables -> Optional[Variable[]]\ The route variables (ones prefixed with a colon).
• callback -> Function\ The actual function that the middleware fires if the method and regex match.

Method

jups.Method{}

All of the HTTP methods that the package supports.

Method Values

• ALL
• GET
• POST
• HEAD
• PATCH
• PUT
• OPTIONS
• CONNECT
• DELETE
• TRACE
• ACL
• BIND
• CHECKOUT
• COPY
• LINK
• LOCK
• M-SEARCH
• MERGE
• MKACTIVITY
• MKCALENDAR
• MKCOL
• MOVE
• NOTIFY
• PROPFIND
• PROPPATCH
• PURGE
• REBIND
• REPORT
• SEARCH
• SOURCE
• SUBSCRIBE
• UNBIND
• UNLINK
• UNLOCK
• UNSUBSCRIBE