npm.io
0.10.0 • Published 4h ago

@novice1/app

Licence
MIT
Version
0.10.0
Deps
1
Size
61 kB
Vulns
0
Weekly
0

@novice1/app

license node

Build Express v5 applications on top of @novice1/routing.

FrameworkApp wraps an Express application and gives you:

  • Routers from @novice1/routing, registered by options or created on the fly.
  • Framework-level middlewares, auth and validators, applied to every registered router.
  • Route metadata (name, tags, ...) available through app.meta.
  • Deferred server creation: http/https servers are created for you, so the Express app never has to be wired by hand.
  • Typed, chainable API written in TypeScript.

Table of contents

Installation

express and @novice1/routing are peer dependencies.

npm install @novice1/app @novice1/routing express

Requires Node.js 18 or later.

Quick start

import routing from '@novice1/routing';
import { FrameworkApp } from '@novice1/app';

const router = routing()
  .get({ path: '/', name: 'Home', tags: ['Index'] }, (req, res) => {
    res.send('Hello world');
  });

const app = new FrameworkApp({
  routers: [router]
});

app.listen(8000, '0.0.0.0', () => {
  console.log('Application started ...');
  console.log(app.meta); // metadata of every registered route
});

CommonJS works too:

const { FrameworkApp } = require('@novice1/app');

Configuration

Pass options to the constructor, or add them later with addOptions().

const app = new FrameworkApp({
  framework: {
    // regular Express middlewares, registered before the routers' routes
    middlewares: [
      (req, res, next) => {
        next();
      }
    ],
    // authorization middlewares
    auth: [
      (req, res, next) => {
        next();
      }
    ],
    // validation middlewares
    validators: [
      (req, res, next) => {
        next();
      }
    ]
  },
  routers: [router]
});
Option Description
middlewares Express middlewares added to the main router.
auth Authorization handlers, set on each router that does not define its own.
validators Validation handlers, set on each router that does not define its own.
routers @novice1/routing routers to register.

auth and validators are only applied to routers that have none of their own.

Adding options later

addOptions() concatenates new options with the current ones. Routers can be added even after the application is built.

app.addOptions({
  routers: [anotherRouter]
});

// or, only routers
app.addRouters([anotherRouter]);

Defining routes

Besides registering routers, you can declare routes directly on the application. They are added to an internal router created with lazyrouter().

app.get({
  path: '/index',
  name: 'Home',
  tags: ['Index']
}, function homepage(req, res) {
  res.send('Home');
});

app.put('/add', (req, res) => {
  // ...
});

app.use((req, res, next) => {
  next();
});

Supported methods: all, get, post, put, delete, patch, options, head, use and param.

You can also create and keep a reference to the router yourself. It is added to the application immediately:

const lazyRouter = app.lazyrouter();

lazyRouter.get({
  path: '/index',
  name: 'Home',
  tags: ['Index']
}, function homepage(req, res) {
  // ...
});

lazyRouter.put('/add', (req, res) => {
  // ...
});

Error handling

Use useError() to register error-handling middlewares. They are mounted after all routes when the application is built (or immediately if it is already built).

app.useError((err, req, res, next) => {
  res.status(500).json({ message: err.message });
});

Starting the server

listen()

listen() builds the application and starts an http.Server. It accepts the same arguments as server.listen() and returns the server.

const server = app.listen(8000, '0.0.0.0', () => {
  console.log('Application started ...');
});
build()

build() builds the application and returns the http.Server without starting it. Calling it again returns the same server. Pass http.ServerOptions, and optionally another module such as https:

const server = app.build({ keepAlive: true });
server.listen(8000);
import https from 'https';

const httpsServerOptions = {
  // key, cert, ...
};

const server = app.build(httpsServerOptions, https);
server.listen(8443);

After building, app.server returns the server, and app.built is true.

Express settings

The usual Express application helpers are available and chainable:

app
  .set('trust proxy', true)
  .enable('etag')
  .disable('x-powered-by');

app.enabled('etag');  // true
app.get('trust proxy'); // true
app.engine('html', renderFn);

API overview

Member Description
new FrameworkApp(options?) Creates the application.
addOptions(options) Concatenates options with the current ones.
addFrameworkOptions(options) Sets middlewares, auth and/or validators.
addRouters(routers) Adds one or several routers.
lazyrouter(options?) Creates a router, adds it to the app and returns it.
all / get / post / put / delete / patch / options / head / use / param Declare routes and middlewares.
useError(...handlers) Registers error-handling middlewares.
build(options?, mod?) Builds the app and creates the server (without listening).
listen(...) Builds the app and starts listening.
set / enable / disable / enabled / disabled / engine / on('mount') Express settings.
meta Metadata of the registered routes.
server, building, built Server instance and build state.

Full documentation is available at kisiwu.github.io/novice-app.

Development

npm run build       # compile TypeScript to lib/
npm test            # run tests against the sources
npm run test:lib    # run tests against the compiled output
npm run lint        # lint
npm run format      # format with Prettier
npm run doc         # generate the documentation

References

License

MIT