JSPM – danf@0.2.2

Package Exports

danf

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (danf) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Introduction

Another javascript/node.js framework??

Yes!

Why?

The main goal of this full-stack framework is to help you organize, rationalize and homogenize your javascript code (website, api, ...) on both the server (node.js) and client (browser) sides.

Which features of this framework can help me to fulfill this goal?

Danf provides several features in order to produce a scalable, maintainable, testable and performant code:

An object-oriented programming layer (formal classes, easy inheritance, ensured interfaces).
An inversion of control design (dependency injection via configuration files).
A simple system allowing to use the same code on both the client and server sides.
A homogeneous way to handle all kind of events (HTTP requests, DOM events, ...).
An elegant solution to callback hell preserving asynchronicity.
A helper to develop performant ajax applications supporting deep linking.
A modular approach to develop and use (open source) modules.
Some other helpful sub features to easily manage cookies, session, ...

What?? An object-oriented programming layer?

Object-oriented programming (OOP) is often a controversial topic in the javascript community. Most of the time, you can observe two reactions:

- But everything is already object in javascript!
- Why the hell do you want to use OOP in javascript?

First, that is not because all variables are objects that a langage can be considered as providing a way to make a straightforward and robust OOP. As for now, native javascript does not allow to make a reliable industrial OOP code (the reasons are explained in the concepts section of the documentation). Then, OOP is certainly not a matter of language, but rather a means of architecturing applications. So why not use OOP for a javascript application?

Hello world

// app.js

var danf = require('danf');

danf({
    config: {
        events: {
            request: {
                helloWorld: {
                    path: '/',
                    methods: ['get'],
                    view: {
                        text: {
                            value: 'Hello world!'
                        }
                    }
                }
            }
        }
    }
});

Installation

$ npm install -g danf

Community

Danf is a brand new framework. It may seem a little hard to handle at the beginning but it can help you to master big projects by avoiding the divergence of the complexity as well as smaller fast and dynamic websites. Just give it a try on one of your project or by testing the tutorial. Be careful, you could see your way of coding javascript in node.js forever change (or not...).

The community is still small, but it is an active community. You can post your issues on github or on stack overflow with the tag danf and you will get an answer as quickly as possible.

<trailer-voice>Have you ever wanted to participate in the early stages of a new technology? Let's try it on Danf! Join the community and contribute now.</trailer-voice>

You can also contribute without working on the framework itself. In Danf, all your code is always automatically part of a danf module. This way you can then easily share your modules with other people using npm. You can find a list of existing danf modules here.

Code examples

Respond to a request with a server class processing

Here is an example of class:

// uppercaser.js

'use strict';

/**
 * Expose `Uppercaser`.
 */
module.exports = Uppercaser;

// Definition of the constructor.
/**
 * Initialize a new uppercaser.
 */
function Uppercaser() {
}

// Definition of the implemented interfaces.
// Here, Uppercaser is implementing the interface "wordProcessor".
Uppercaser.defineImplementedInterfaces(['wordProcessor']);

// Implementation of the method of the interface.
/**
 * @interface {wordProcessor}
 */
Uppercaser.prototype.process = function(word) {
    return word.toUpperCase();
}

Here is an example of application using this class:

// app.js

'use strict';

var danf = require('danf');

danf({
    config: {
        // Declaration of the class.
        classes: {
            uppercaser: require('./uppercaser')
        },
        // Definition of the interface implemented by this class.
        interfaces: {
            wordProcessor: {
                methods: {
                    process: {
                        arguments: ['string/word'],
                        returns: 'string'
                    }
                }
            }
        },
        // Definition of a service using this class.
        services: {
            uppercaser: {
                class: 'uppercaser'
            }
        },
        // Definition of a sequence using this service.
        sequences: {
            uppercaseName: [
                // Pass the field "name" of the input stream as first argument
                // to the method "process" of the service "uppercaser".
                {
                    service: 'uppercaser',
                    method: 'process',
                    arguments: ['@name@'],
                    returns: 'name'
                }
            ]
        },
        // Definition of an event of kind HTTP request using this sequence.
        events: {
            request: {
                hello: {
                    path: '/',
                    methods: ['get'],
                    // Description of expected input stream coming from requests.
                    parameters: {
                        name: {
                            type: 'string',
                            default: 'world'
                        }
                    },
                    // Definition of the used view.
                    view: {
                        html: {
                            body: {
                                file: __dirname + '/hello.jade'
                            }
                        }
                    },
                    // Description of the executed sequences.
                    sequences: ['uppercaseName']
                }
            }
        }
    }
});

And here is the view:

//- hello.jade

h1
  = 'Hello ' + name + '!'

Test it executing: $ node app.js

Use a class on both the client and server sides

Here is a class both usable in the browser and in node.js:

// logger.js

'use strict';

// Define "define" for the client or the server.
var define = define ? define : require('amdefine')(module);

// Wrapper allowing to use the class on both the client and server sides.
define(function(require) {
    /**
     * Initialize a new logger.
     */
    function Logger() {}

    Logger.defineImplementedInterfaces(['logger']);

    /**
     * @interface {logger}
     */
    Logger.prototype.log = function(message) {
        console.log(message);
    }

    /**
     * Expose `Logger`.
     */
    return Logger;
});

Here is the app file:

// app.js

'use strict';

var danf = require('danf');

danf(require('./danf'));

Here is the danf server configuration entry file:

// danf.js

'use strict';

var utils = require('danf/lib/utils');

module.exports = {
    config: utils.merge(
        // Merge common and server config.
        require('./common-config'),
        require('./server-config'),
        true
    )
};

Here is the danf client configuration entry file:

// danf-client.js

'use strict';

define(function(require) {
    var utils = require('danf/utils');

    return {
        // Merge common and client config.
        config: utils.merge(
            require('my-app/common-config'),
            require('my-app/client-config'),
            true
        )
    };
});

Here is the server config file:

// server-config.js

'use strict';

module.exports = {
    // The assets are the rules defining which files are accessible from HTTP requests.
    assets: {
        // Define the path for "danf-client".
        // You always need to define this path.
        'danf-client': __dirname + '/danf-client',
        // Map "my-app" to the current directory.
        // The URL path "/my-app/client-config" will give the file "client-config.js".
        'my-app': __dirname,
        // Forbid access to the file "server-config".
        '!my-app/server-config': __dirname + '/server-config.js'
    },
    // The definition of the classes is a little bit different for the client and the server.
    classes: {
        logger: require('./logger')
    },
    // Log on the HTTP request of path "/".
    events: {
        request: {
            index: {
                path: '/',
                methods: ['get'],
                view: {
                    html: {
                        body: {
                            file: __dirname + '/index.jade'
                        }
                    }
                },
                sequences: ['logDanf']
            }
        }
    }
};

Here is the client config file:

// client-config.js

'use strict';

define(function(require) {
    return {
        classes: {
            // You must use "my-app/logger" on the client side.
            // "my-app" is the name you defined in the assets of your server config.
            logger: require('my-app/logger')
        },
        // Log on the DOM ready event.
        events: {
            dom: {
                ready: {
                    event: 'ready',
                    sequences: ['logDanf']
                }
            }
        }
    }
});

Here is the common config file:

// common-config.js

'use strict';

var define = define ? define : require('amdefine')(module);

define(function(require) {
    return {
        interfaces: {
            logger: {
                methods: {
                    log: {
                        arguments: ['string/message']
                    }
                }
            }
        },
        services: {
            logger: {
                class: 'logger'
            }
        },
        sequences: {
            logDanf: [
                {
                    service: 'logger',
                    method: 'log',
                    arguments: ['Powered by Danf']
                }
            ]
        }
    }
});

Finally, here is the view:

//- index.jade

h1 Take a look at your console!

Test it executing: $ node app.js

How to organise all this code? Use the available proto application to help you start a new danf module!

Inject services into each others

Here is an example of config with effective dependency injection:

// app.js

'use strict';

var danf = require('danf');

danf({
    config: {
        classes: {
            processor: {
                // "adder" and "multiplier" inherit from "abstract".
                // You can see how it works in the details of the classes below.
                abstract: require('./abstract-processor'),
                adder: require('./adder'),
                multiplier: require('./multiplier')
            },
            parser: require('./parser'),
            computer: require('./computer')
        },
        interfaces: {
            computer: {
                methods: {
                    compute: {
                        arguments: ['string/operation'],
                        returns: 'string'
                    }
                }
            },
            processor: {
                methods: {
                    process: {
                        arguments: ['number/operand1', 'number/operand2'],
                        returns: 'number'
                    }
                },
                getters: {
                    operation: 'string'
                }
            },
            parser: {
                methods: {
                    parse: {
                        arguments: ['string/operation'],
                        returns: 'string_array'
                    }
                }
            }
        },
        services: {
            processor: {
                tags: ['processor'],
                // Define children services which will inherit the tag.
                // This feature is mainly used to improve readability.
                // The names of the services are "processor.adder" and "processor.multiplier".
                children: {
                    adder: {
                        class: 'processor.adder'
                    },
                    multiplier: {
                        class: 'processor.multiplier'
                    }
                }
            },
            parser: {
                class: 'parser'
            },
            computer: {
                class: 'computer',
                // Set the properties of the service "computer".
                properties: {
                    // Inject in the property "parser" the service "parser".
                    parser: '#parser#',
                    // Inject in the property "processors" the services tagged with "processor".
                    processors: '&processor&'
                }
            }
        },
        sequences: {
            computeOperation: [
                {
                    service: 'computer',
                    method: 'compute',
                    arguments: ['@operation@'],
                    returns: 'result'
                }
            ]
        },
        events: {
            request: {
                hello: {
                    path: '/',
                    methods: ['get'],
                    parameters: {
                        operation: {
                            type: 'string',
                            required: true
                        }
                    },
                    view: {
                        html: {
                            body: {
                                file: __dirname + '/index.jade'
                            }
                        }
                    },
                    sequences: ['computeOperation']
                }
            }
        }
    }
});

Here is the related classes and view:

// abstract-processor.js

'use strict';

/**
 * Expose `AbstractProcessor`.
 */
module.exports = AbstractProcessor;

/**
 * Initialize a new abstract processor.
 */
function AbstractProcessor() {
    Object.hasGetter(this, 'neutralElement');
    Object.hasMethod(this, 'processOperation');
}

AbstractProcessor.defineImplementedInterfaces(['processor']);

// Define the class as an abstract non instantiable class.
AbstractProcessor.defineAsAbstract();

/**
 * @interface {processor}
 */
AbstractProcessor.prototype.process = function(operand1, operand2) {
    if (undefined === operand2) {
        operand2 = this.neutralElement;
    }

    return this.processOperation(operand1, operand2);
}

// adder.js

'use strict';

/**
 * Expose `Adder`.
 */
module.exports = Adder;

/**
 * Initialize a new adder processor.
 */
function Adder() {
}

Adder.defineImplementedInterfaces(['processor']);

// Define the inherited class.
Adder.defineExtendedClass('processor.abstract');

/**
 * @interface {processor}
 */
Object.defineProperty(Adder.prototype, 'operation', {
    get: function() { return '@'; }
});

/**
 * @inheritdoc
 */
Object.defineProperty(Adder.prototype, 'neutralElement', {
    get: function() { return 0; }
});

/**
 * @inheritdoc
 */
Adder.prototype.processOperation = function(operand1, operand2) {
    return operand1 + operand2;
}

// multiplier.js

'use strict';

/**
 * Expose `Multiplier`.
 */
module.exports = Multiplier;

/**
 * Initialize a new multiplier processor.
 */
function Multiplier() {
}

Multiplier.defineImplementedInterfaces(['processor']);

// Define the inherited class.
Multiplier.defineExtendedClass('processor.abstract');

/**
 * @interface {processor}
 */
Object.defineProperty(Multiplier.prototype, 'operation', {
    get: function() { return '*'; }
});

/**
 * @inheritdoc
 */
Object.defineProperty(Multiplier.prototype, 'neutralElement', {
    get: function() { return 1; }
});

/**
 * @inheritdoc
 */
Multiplier.prototype.processOperation = function(operand1, operand2) {
    return operand1 * operand2;
}

// parser.js

'use strict';

/**
 * Expose `Parser`.
 */
module.exports = Parser;

/**
 * Initialize a new adder processor.
 */
function Parser() {
}

Parser.defineImplementedInterfaces(['parser']);

/**
 * @interface {processor}
 */
Parser.prototype.parse = function(operation) {
    return operation.split(' ');
}

// computer.js

'use strict';

/**
 * Expose `Computer`.
 */
module.exports = Computer;

/**
 * Initialize a new adder processor.
 */
function Computer() {
    this._processors = {};
    this._parser;
}

Computer.defineImplementedInterfaces(['computer']);

// Define dependencies in order to check their correct injection, ensure interfaces, ...
Computer.defineDependency('_parser', 'parser');
Computer.defineDependency('_processors', 'processor_object');

/**
 * @interface {processor}
 */
Computer.prototype.compute = function(operation) {
    var parsedOperation = this._parser.parse(operation),
        result = parseInt(parsedOperation.shift(), 10)
    ;

    for (var i = 0; i < parsedOperation.length; i = i + 2) {
        result = getProcessor.call(this, parsedOperation[i])
            .process(result, parseInt(parsedOperation[i + 1]))
        ;
    }

    return result;
}

Object.defineProperty(Computer.prototype, 'parser', {
    set: function(parser) { this._parser = parser; }
});

Object.defineProperty(Computer.prototype, 'processors', {
    set: function(processors) {
        for (var i = 0; i < processors.length; i++) {
            var processor = processors[i];

            this._processors[processor.operation] = processor;
        }
    }
});

/**
 * @interface {processor}
 */
Computer.prototype.parse = function(operation) {
    return operation.slit(' ');
}

var getProcessor = function(operation) {
    if (undefined === this._processors[operation]) {
        throw new Error('No operation "{0}" found.'.format(operation));
    }

    return this._processors[operation];
}

//- index.jade

p
  = 'Result: ' + result

Test it executing: $ node app.js

http://localhost:3080/?operation=3 * 2 @ 4 // Result: 10

http://localhost:3080/?operation=3 @ 2 * 4 // Result: 20

Documentation

Learn more about the framework in the documentation.

License

Open Source Initiative OSI - The MIT License

http://www.opensource.org/licenses/mit-license.php

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.