jagg-web v1.0.4-stable

Jagg WEB

This is Jagg's main orchestrator.

Jagg is a pre-built and modular WEB API/REST development framework oriented towards configurations and the use of prefabricated components and the reduction of software development.

Requirements

The Jagg WEB require:

• A MongoDB server.

The hello world

# Download container
sudo docker pull mongo:latest;

# Create the database container
sudo docker create \
    -p 127.0.0.1:27017:27017 \
    -e MONGO_INITDB_ROOT_USERNAME=dev \
    -e MONGO_INITDB_ROOT_PASSWORD=dev \
    -e DB_NAME=dev \
    -e DB_USER=dev \
    -e DB_PASSWORD=dev \
    --name mongodb \
    mongo:latest;

# Start database container
sudo docker start mongodb;

# Create the starter project
touch index.js;
npm init;
npm install jagg-web;

The hello world index.js:

const { JaggWeb } = require('jagg-web');
const jaggWeb = new JaggWeb({
    mongodb: { user: 'dev', password: 'dev' }
});
jaggWeb.run();

In the package.json set the start script:

"scripts": {
    "start": "node index.js"
},

And run the project:

# Run the project
npm start;

[2024-01-01 00:00:00] [INFO] Jagg WEB v1.0.0-stable
[2024-01-01 00:00:00] [INFO] Connecting to the database ...
[2024-01-01 00:00:00] [INFO] Initializing middleware ...
[2024-01-01 00:00:00] [INFO] Binding HTTP server ...
[2024-01-01 00:00:00] [INFO] Listen on http//127.0.0.1:3000/
[2024-01-01 00:00:00] [REQ] [127.0.0.1] [404] [GET] /
[2024-01-01 00:00:00] [REQ] [127.0.0.1] [404] [GET] /foo

The Jagg components

You can use other Jagg components, like as, auth, pages or contact, by example:

const { JaggWeb } = require('jagg-web');
const { jaggAuth } = require('jagg-auth');
const { jaggContact } = require('jagg-contact');
const { jaggPages } = require('jagg-pages');

(new JaggWeb({
    mongodb: { user: 'dev', password: 'dev', /* ... */ },
    // ...
}))
.use(jaggAuth({
    publicRegistration: false, /* ... */
}))
.use(jaggContact({
    smtp: { /* ... */ },
    title: { /* ... */ },
    subject: { /* ... */ },
    recaptcha: { /* ... */ },
    // ...
}))
.use(jaggPages())
.run();

You can make custom middleware using the express route from jaggWeb.expressApp.

Options

The JaggWeb class constructor contains the following options and defaults:

new JaggWeb({
    server: { host: `127.0.0.1`, port: 3000 },
    mongodb: { host: `127.0.0.1`, port: 27017,
        dbname: 'app', user: null, password: null },
    swagger: true,
    log: { info: true, requests: true }
});

- `server.host`: The host or ip address to bind HTTP service.
- `server.port`: The port to bind HTTP service.
- `mongodb.host`: The host or ip address of the MongoDB connection.
- `mongodb.port`: The port of the MongoDB connection.
- `mongodb.dbname`: The name of the MongoDB database.
- `mongodb.user`: The username of the MongoDB connection.
- `mongodb.password`: The password of the MongoDB connection.
- `swagger`: Set the Swagger UI enabled.
- `log.info`: Indicates whether the information logs should be shown.
- `log.requests`: Indicates whether the requests logs should be shown.

Error handlers

You can handle errors from:

// Single import
const { errors } = require('jagg-web');

// Contextual import
const jagg = require('jagg-web');
jagg.errors

• DuplicatedError: Fired when save a duplicated unique document.
• NotFoundError: Fired when try access to and non-existent document.
• SchemaError: Fired when user send a bad input schema (body) for the API function.

But don't worry, this is managed automatically.

Logs

You can manage logs using log object:

// Single import
const { log } = require('jagg-web');

log.info(`Hello world.`)

Log styles available:

• info: Write a log message with the date and time.
• error: Write a error log message with the date and time.
• request: Write a request message with the date and time.
• li: Write a request message with the start space and - as list style.

Validations

For validations use validation.type or validation.typeRegExp, like as:

const { validation } = require('jagg-web');

console.log(validation.email('Foo'));
// false

validation.emailRegExp;
// /^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*$/

The list of validation types are:

• uuid: Validates if the value is in UUID format.
• bsonId: Validates if the value is in Bson id format.
• dni: Validates if the value is a valid DNI.
• name: Validates if the value is a valid Name.
• schemaName: Validates if the value is a valid schema name.
• title: Validates if the value is a valid title.
• email: Validates if the value is a valid email.
• phone: Validates if the value is a valid phone number.
• languageIso: Validates if the value is a valid language iso format.
• hostname: Validates if the value is a valid hostname or ip address.
• ipAddress: Validates if the value is a valid ip address.
• userAgent: Validates if the value is a valid Browser User Agent.
• bcrypt: Validates if the value is a valid Bcrypt hash.
• password: Validates if the value is a valid and secure Password.
• uri: Validates if the value is a valid URI/URL.

You can made validations using jsonschema component:

const { validation } = require('jagg-web');

/*
Validate schema or throw a SchemaError object with SchemaError.errors
The function is async.
*/
(req, res, next) => {
    /*
    Security preventions:
    - https://cwe.mitre.org/data/definitions/20.html (Improper Input Validation)
    - https://cwe.mitre.org/data/definitions/943.html (Improper Neutralization of Special Elements in Data Query Logic)
    - http://capec.mitre.org/data/definitions/676.html (NoSQL Injection)
    */
    validation.validSchemaOrThrow(req.body, {
        type: 'object',
        properties: {
            email: { type: 'string', pattern: validation.emailRegExp },
            password: { type: 'string', pattern: validation.passwordRegExp },
        },
        required: [ 'email', 'password' ]
    })
    .then(() => service.foo(req.body))
    .then(data => res.status(200).json(data))
    .then(() => next())
    .catch(e => next(e))
}