Cardigan

Cardigan is a framework over Express.js to quickly spin up a node js back end server. It handles all the basic stuff a 90% of web apps needs. The framework is over Express.js so you can extend it and use any Express.js library and even integrate it with Socket.IO. This project is backed by @redcarpetsolutions

Installation

Right now this module is only available on NPM

npm i rcs-cardigan

You don't need --save (-S) if you're using NPM@5

Getting Started

Cardigan exposes an "app" object that is exactly like the app object you will get when creating an express application with 'express()'. It exposes a couple mode diffrent methods that do the magic behind the framework

const app = require('rcs-cardigan').app;
const options = {};
app.start(options);

this is all you need to start your application. the options object must contain 2 main parameters.

const app = require('rcs-cardigan').app;
const options = {
    databaseUrl:"MONGODB_DATABASE_FULL_URL",
    port:"PORT_TO_LISTEN_ON"
};
app.start(options);

note that this is will not display anything and your application does nothing at this point.

Persisting Data

Cardigan handles persisting your data model in a Mongo DB database (defined in the app.start(options)).

Data Models

To create a data Model, Cardigan exposes a Model class:

// Your getting started code goes here :)
const Model = require('rcs-cardigan').Model;
const Product = new Model('products');

'products' will be the name of the MongoDB collection in your database.

This command will generate a Non-strict data model that will accept any json object you want to persist.

We are working on a data model validator, will be out soon.

Interact with your Data

To interact with your data, Cardigan automaticly generates RestFull APIs that allows you to access your data (All the necessary CRUD Operations).

// Your getting started code goes here :)
const Model = require('rcs-cardigan').Model;
const Product = new Model('products');
app.addCollection(Product);

Cardigan Will Display in the console the routes available to interact with the Collection created.

Access Control

Cardigan Has a built in full authentication libarary that you can enable by chosing a data model (See above) as your user model.

// Your getting started code goes here :)
const Model = require('rcs-cardigan').Model;
const User = new Model('users');
app.authModel(User);

Default Features

Cardigan requires your user model to have multiple fields:

{
    "email":"A_VALID_EMAIL",
    "password":"SALTED_HASHED_PASSWORD",
    "salt":"SALT_OF_THE_PASSWORD",
    "valid":"IS_THE_ACCOUNT_VALIDATED",
    "role":"ROLE_OF_THE_USER"
}

email and password are the main authentication fields. the password is hashed using bcrypt with an added salt. valid is the boolean to check if you have email validation activated (check below) role is a string that determines if the user is Authorized to access a certain resource (equals "user" by default).

Registration

To register you to send a POST request to the registration Endpoint generated by Cardigan. your json object have to contain

const user = {
    "email:"", // required
    "password":"", // required
    "role":"" // Optional if you want the user to have a specific role.
};

Login

To login you to send a POST request to the login Endpoint generated by Cardigan. your json object have to contain

const user = {
    "email:"", // required
    "password":"" // required
};

you will receive a user object and a token. See our response section to know more about the format of the JSON object you will receive.

Email Validation

You can enable email validation by adding an options object to the authentication model.

// Your getting started code goes here :)
const Model = require('rcs-cardigan').Model;
const User = new Model('users');
const options = {};
app.authModel(User,options);

the options object have the followin attributes:

const options = {
    emailValidation:true, // False By Default
    emailContent:emailTemplate // Has a default template
}

the email template is a simple HTML string. Example :

const emailTemplate = `
<h1> Email Validation</h1>
<p> Thank you for using our framework, here's your validation link:</p>
`;
const options = {
    emailValidation:true,
    emailContent:emailTemplate 
}

The validation link will be added at the end of the template. Working on making it possible to include it in a custumizable position as a customizable HTML element.

Security

This authentication Module uses JWT (JSON Web Tokens) as it's main authentication/authorization tool.

Currently working on a better Access Control for the APIs.

Sugar On Top :3

In App Documentation

We are currently working on an endpoint to help you navigate visually through your backend. the current route for that right now is /rcs/routing. Alternatively, Running the application will automaticly display all the routes it generated.

Replacing Provider in Responses

app.setProvider('PROVIDER_NAME') will change the provider returned in the Json object of all the json response;

Best Practices

Data Models

you can declare your data models in seperate files from your main file:

const Model = require('rcs-cardigan').Model;
const Event = new Model('events');

module.exports = Event;

Response Model

We are using a library to generate our responses. to check our standard for HTTP responses please check: rcs-jsonstyle

Issues

We are actively working on this project and using it in production. Please do not hesitate to leave an Issues if you run into any trouble.

Troubleshooting

App.start()

app.start() should be the first function to be called if your main file. You might experience weird behavior otherwise.

MongoDB errors

If you try to immidiatly access the database after app.start(), the app will exit with an error because the connection to the database is asyncronus.

Red Carpet Solutions

We're a Company What do we do!

This project is backed By redcarpetsolutions

About the Author

I'm Khaled Romdhane but mostly known as heiyuki. My handle is : @heiyukidev.

I Work at this amazing Company @redcarpetsolutions don't hesitate to go check us out.