Expressive

Build structured backend apps with express.js without caring about asynchronous code execution and error management.

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Installation
   • Basic usage
3. Development
   • Installation
   • Build
4. Contributing
5. License
6. Contact

About The Project

During development phase of a Node.js + Express project, I'm constantly questioning the file structure of the project and links between different domains of the application. Also, I'm often in trouble when it comes to split responsibilities across many files while trying to keep things simple and stupid. Add to this asynchronous code handling and exception management, and you get the portrait.

I needed a robust solution that meets all these requirements while hiding boilerplate code : Expressive was born.

Expressive is a tiny package, exposing an Express middleware and some helper functions that ensure that :

• Routers and controllers are two well-defined components of the app, each one having different responsibilities ;
• Asynchronous code handling is as simple as making your controller returning a Promise ;
• Error handling is enhanced with standard HTTP exception catching.

Built With

• Node.js
• Yarn
• TypeScript

Getting Started

Installation

Install the package by running :

npm install @corentind/expressive

or using Yarn :

yarn add @corentind/expressive

Basic usage

The code snippet below shows a basic example of how to use expressive with express.

import express from 'express';
import expressive, { handle, Ok, NotFound } from '@corentind/expressive'

// Here is your service layer
import { getById } from './service';

// Controller doesn't know about req or res objects.
async function getTodoById(id) {
    try {
        
        // Asynchronous handling made easy
        const todo = await getById(id);
        
        // Returns a JavaScript literal as a JSON object with 200 status code
        return new Ok(todo);
    } catch (e) {
        
        // Exception handling can be done exhaustively here.
        if (e.name === 'NotFoundError') {
            
            // Standard error format for simpler API contract
            throw new NotFound({
              code: 'todo-not-found',
              message: `Todo with ID ${id} could not been found`
            });
        }
        
        // Expressive will catch any unhandled error, log it and return a 500 error to the client
        throw e;
    }
}

const app = express();

// `handle` allows expressive to correctly process the asynchronous controller
app.get('/todos/:id', handle(({ params: { id } }) => getTodoById(id)));

// `expressive` middleware is the brain of the lib
app.use(expressive());

app.listen(process.env.PORT || 3000);

For more examples, please refer to the Documentation (WIP)

Development

Installation

1. Clone the repo

git clone https://github.com/corentind59/expressive.git

2. Install NPM packages with Yarn

yarn

Build

yarn build

The project output will be generated in the dist folder.

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Corentin Delannoy - corentin.delannoy2@gmail.com

Project Link: https://github.com/corentind59/expressive