dingle

    0.2.5 • Public • Published

    Dingle Logo

    Dingle is a quick and easy NodeJS module which can be used to create scalable and maintainable API backends.

    Installation

    $ npm install --save dingle

    Features

    • HTTP, HTTPS, TCP & UDP
    • Parameter Validation
    • File Download & Uploads
    • Client Code Generator
    • JSON Input & Output

    Generators

    Our generator modules allow you to build client side code automatically which are built from your dingle functions and parameters.

    Startup

    To start dingle it requires a minimum of an ip to listen on:

    var dingle = require('dingle')({
        http_listen: '0.0.0.0',
        https_listen: '0.0.0.0',
        tcp_listen: '0.0.0.0',
        udp_listen: '0.0.0.0'
    });

    In dingle each API call is referred to as a function.

    Directory Layout

    Each function exists in a module and is loaded from the public directory like so:

    public
    ├───status.js
    ├───time.js
    ├───users.js
    ├───users
    │   └───register.js
    │   └───forgot_username.js
    │   └───forgot_password.js
    │   └───sessions
    │       └───login.js
    │       └───logout.js
    │       └───list.js
    

    Each function is referred to using a naming convention where directories are separated by underscores:

    status
    time
    users
    users_register
    users_forgot_username
    users_forgot_password
    users_sessions_login
    users_sessions_logout
    users_sessions_list
    

    Also note function names ARE case sensitive.

    HTTP & HTTPS

    To access the functions via HTTP or HTTPS we use the URL:

    https://myawesomeapi.com/users_forgot_username/?email=admin@myawesomeapi.com&password=myawesomeapi.com
    

    TCP & UDP

    To access the functions via TCP or UDP you must first make a connection using either protocol and send data using the following format:

    /users_forgot_username/email=admin@myawesomeapi.com&password=myawesomeapi.com
    

    Basic Function

    The module for each function is laid out as follows:

    • exports.brief - Function in a few words.
    • exports.description - Function in a few more words.
    • exports.methods - Array of methods to broadcast this function on: TCP, UDP & HTTP Methods
    • exports.params - Object of parameters the function requires.
    • exports.execute - Array of series functions to execute when the function is called upon.
    //Setup
    exports.brief = "Register Users"
    exports.description = "Use this function to create a user in the MongoDB database before they are given access to the website.";
    exports.methods = [ "GET" ];
     
    //Parameters
    exports.params = {};
    exports.params.email = {
        description: 'Email for registering user'
    }
    exports.params.password = {
        description: 'Password for registering user'
    }
     
    //Execution
    exports.execute = [function(response, params, info, next){
        
        //Create User
        var user = new NewUser({
            email: params.email,
            password: params.password
        });
     
        //Save User to MongoDB
        user.save(function (error){
            if (error){
                next(error, response, params, info);
            }else{
                //Add user to response
                response.output.user_id = user._id;
                
                next(null, response, params, info);
            }
        });
    }];

    You can also use our Dingle Validator module to import our set of pre-defined data types.

    Advanced Function

    The parameter object layout goes like so:

    • exports.params[].description - Parameter in a sentence.
    • exports.params[].required - Boolean whether parameter is required. (If false and no value given param will be an null value)
    • exports.params[].validator - Function used to validate parameter. Throw an error if not valid and return object in the correct data type.

    The execute object layout goes like so:

    • exports.execute[](response) - Object containing message and output property which will be returned from the function.
    • exports.execute[](params) - Object of validated parameters given from exports.params.
    • exports.execute[](info.address) - Holds the users IP address of the user.
    • exports.execute[](info.functions) - List of functions in dingle and functions to execute them. (See below)
    • exports.execute[](info.temp) - Blank object to store temp data being passed through the functions.
    • exports.execute[](next) - Function to call to move onto the next item in the function array. The first parameter is either null to continue executing or an error string to stop execution and return the error message.
    var validator = require('validator');
     
    //Setup
    exports.brief = "Register Users"
    exports.description = "Use this function to create a user in the MongoDB database before they are given access to the website.";
    exports.methods = [ "GET", "POST" ,"TCP", "UDP" ];
     
    //Parameters
    exports.params = {};
    exports.params.email = {
        description: 'Email for registering user',
        validator: function(object){
            if (!validator.isEmail(object)){
                throw "Please enter a valid email adress";
            }else{
                return object.toString();
            }
        }
    }
    exports.params.password = {
        description: 'Password for registering user'
    }
    exports.params.news = {
        description: 'User would like to recieve news',
        required: false,
        validator: function(object){
            if (!validator.isBoolean(object)){
                throw "Please enter true or false for news";
            }else{
                return object.toBoolean();
            }
        }
    }
     
    //Execution
    exports.execute = [];
    exports.execute[0] = function(response, params, info, next){
        
        //Create User
        info.temp.user = new NewUser({
            email: params.email,
            password: params.password
        });
     
        //Add user to response
        response.output.user_id = user._id;
        
        next(null, response, params, info);
    }
    exports.execute[1] = function(response, params, info, next){
        
        //Save User to MongoDB
        info.temp.user.save(function (error){
            if (error){
                next(error, response, params, info);
            }else{
                next(null, response, params, info);
            }
        });
    }

    Executing Functions

    You can execute functions from within another function using the info.functions object like so:

    exports.execute[0] = function(response, params, info, next){
        
        info.functions['users_forgot_username'].run(params, function(success, message, output){
            
            //Collect result from function
            response.message = message;
            response.output = output;
            
            //Respond with result
            if (success){
                next(null, response, params, info);
            }else{
                next(message, response, params, info);
            }
            
        });
    }

    We can even execute a function from outside dingle:

    var dingle = require('dingle')({
        http_listen: '0.0.0.0',
        https_listen: '0.0.0.0',
        tcp_listen: '0.0.0.0',
        udp_listen: '0.0.0.0'
    });
     
    dingle.functions['users_forgot_username'].run({
        email: 'admin@myawesomeapi.com',
        password: 'myawesomepassword',
    }, function(success, message, output){
        console.log(success);
        console.log(message);
        console.log(output);
    });

    File Downloads

    When using HTTP or HTTPS files can be downloaded from a function using the download property like so:

    exports.execute[0] = function(response, params, info, next){
        
        //Download README.md
        response.download = './README.md';
        
        next(null, response, params, info);
    }

    When downloading a file the message and output properties of the response object will not be displayed.

    File Uploads

    When uploading files using the POST method the following Multer object is returned in the params property:

    • fieldname - Field name specified in the form.
    • originalname - Name of the file on the user's computer.
    • name - Renamed file name.
    • encoding - Encoding type of the file.
    • mimetype - Mime type of the file.
    • path - Location of the uploaded file.
    • extension - Extension of the file.
    • size - Size of the file in bytes.
    • truncated - If the file was truncated due to size limitation.
    • buffer - Raw data (is null unless the inMemory option is true).

    It's your job to manipulate, read and clean up when finished.

    Additional Options

    There are further options which can be used as follows:

    • app_name - Long name of your app.
    • app_prefix - Abbreviation which are used for exports when compiling code.
    • app_version - Version of your app.
    • path_functions - Default path for all functions.
    • path_downloads - Default path for download files.
    • path_uploads - Default path for upload files.
    • *_hostname - Publicly accessible hostname or IP.
    • *_listen - Local hostname or IP to listen on.
    • *_port - Port to listen at.
    var dingle = require('dingle')({
        
        //App (Default from package.json)
        app_name: 'My Awesome App',
        app_prefix: 'MAA',
        app_version: '0.0.7',
        
        //Paths
        path_functions: './public',
        path_downloads: './downloads',
        path_uploads: './uploads',
        
        //HTTP
        http_hostname: 'myawesomeapi.com',
        http_listen: '0.0.0.0',
        http_port: 80,
        
        //HTTPS
        https_hostname: 'myawesomeapi.com',
        https_listen: '0.0.0.0',
        https_port: 443,
        https_ssl_key: './key.pem',
        https_ssl_cert: './cert.pem',
        
        //TCP
        tcp_hostname: 'myawesomeapi.com',
        tcp_listen: '0.0.0.0',
        tcp_port: 7691,
        
        //UDP
        udp_hostname: 'myawesomeapi.com',
        udp_listen: '0.0.0.0',
        udp_port: 7692
    });

    Customization

    You can access internal modules dingle uses to run to gain more functionality using the following properties:

    • config - Startup configuration for dingle.
    • functions - Object with function information.
    • express - Express app instance.
    • tcp - Standard net TCP sever.
    • udp - Socket for UDP server.
    var dingle = require('dingle')({
        http_listen: '0.0.0.0',
        https_listen: '0.0.0.0',
        tcp_listen: '0.0.0.0',
        udp_listen: '0.0.0.0'
    });
     
    console.log(dingle.functions);

    Install

    npm i dingle

    DownloadsWeekly Downloads

    0

    Version

    0.2.5

    License

    MIT

    Last publish

    Collaborators

    • victor96