Natural Pleistocene Monsters
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    mdoqpublic

    mdoq

    Build and execute stacks of connect, express, and FlatIron style middleware in Node.js and the browser.

    Problem

    I have a source of data (a database, a REST api, etc) and I have a request for data.

    Typical Solution

    Usually the solution looks a lot like this:

    ArticleProvider.prototype.findAll = function(callback) {
      this.db.collection('articles', function(error, article_collection) {
        // ... and so on ... http://howtonode.org/express-mongodb
      });
    };
    

    Now you can "provide" data to the request in, for example, an express route.

    var articleProvider = new ArticleProvider();
    
    app.get('/articles', function(req, res){
      articleProvider.findAll(function(err, docs){
        // and respond ...
      })
    });
    

    Example Solution

    Instead of reinventing the interface (eg. ArticleProvider), proxy and filter data over the existing http interface with mdoq.

    var articles = mdoq.require('mdoq-mongodb').use('/articles');
    
    app.get('/articles', articles.proxy());
    

    Mdoq supports execution without a server.

    articles.get({author: 'joe bob'}, function(err, res) {
      console.log(res) // articles by joe bob
    });
    

    Re-use mdoq middleware to filter and pipe data between sources.

    var articles = mdoq.require('mdoq-mongodb').use('/articles')
      , feed = mdoq.require('mdoq-http').use('http://articles.com/feed.json');
    
    function combine(req, res, next, end) {
      res.articles = res.data;
      end(function(req, res) {
        if(req.data.concat && req.data.length) {
          res.body = req.data.concat(res.articles);
        }
        next();
      })
      next();
    }
    
    // get articles from db and rss feed
    articles.use(combine).use(feed).get(function(err, res) {
      console.info(res); // [ ...MongoDB and Feed Articles... ]
    })
    

    More Examples

    By itself, mdoq only builds middleware stacks and request objects. It is up to other middleware to fetch and or modify data while updating the response.

    // if you use mdoq alone
    var mdoq = require('mdoq');
    
    // nothing much will happen
    mdoq.use('/blog/articles').post({author: 'joe bob'}, function(err, res) {
      console.info('mdoq built this request:', this.req);
    });
    

    Mdoq will build a request, then execute the request against any middleware being used.

    mdoq built this request: { method: 'POST',
      data: { author: 'joe bob' },
      headers: {},
      url: '/blog-post' }
    

    Add in middleware by calling use() on the current mdoq object. Calling use() will return a new mdoq context. This is useful for reusing middleware stacks against different urls.

    var http = mdoq.use(mdoq.http())
      , blog = http.use('/blog')
      , articles = blog.use('/articles');
      
    articles.post({author: 'jimmy jones'}, function(err, res) {
      console.info(res); // the http response body
    });
    

    Features

    • A consistent http api for building server and client middleware
    • Works in Node.js, and modern browsers
    • Tools for debugging and testing middleware
    • Modular design for intuitive comprehension and small footprint

    Middleware

    Middleware is not bundled. Instead middleware is built separately as independent modules.

    • http - execute http requests in Node.js and via jQuery in the browser
    • mongodb - proxy http requests into mongodb to read and write documents with an http api
    • offline - pass all requests through a local browser persistence layer and automatically sync when the network is available
    • debug - trace out http information such as url, response, duration, and errors
    • faux - test new middleware implementations against a faux datasource

    Modifiers

    Middleware may expose functions that will patch mdoq's api. This is useful for methods that should only be included in the api once a middleware is added.

    The mongodb middleware uses this to add methods such as first().

    // example middleware
    function middleware(req, res, next) {
      // modify the req and or res and call next with any errors
      next();
    }
    
    // add a modifier that will patch the current mdoq context
    middleware.example = function(str, num, etc) {
      console.info(this); // the currently executing mdoq context
      console.info(this.req);
      console.info(this.res);
      
      // always return this
      return this;
    }
    

    API

    All methods in mdoq return an mdoq object (think jQuery).


    mdoq.use(middleware | url | context)

    url String

    Calling use() with urls allows separate execution contexts. This is useful for controlling when certain middleware are used.

    var api = mdoq.use('http://localhost:3000')
      , users = api.use('/users');
    

    middleware MiddlewareFunction(req, res, next, use)

    A function to add to the middleware stack.

    context Object

    A separate mdoq object containing a middleware Array to be added to the current stack.

    var db = mdoq.require('mdoq-mongodb').use('mongodb://localhost') , cache = mdoq.require('my-cache-middleware') , tweets = db.use('/tweets')

    returns

    A new mdoq object. This can be chained to switch contexts, such as a MongoDB collection or a URL part.

    var db = mdoq.use('mongodb://localhost')
      , users = db.use('users');
    

    MiddlewareFunction(req, res, next, end)

    Middleware are functions executed in the order they are use()d. Middleware modify the provided req and res objects and call next() to continue to the next middleware in the stack.

    next Function(err)

    Can be called with an optional err object. This err object will be added to the current mdoq object at mdoq.err.

    end Function(middleware)

    For adding middleware to the end of the stack during execution. Useful for middleware that require execution before and after other middleware.

    mdoq.use(function(req, res, next, end) {
      // automatically handle data as JSON
      if(!res.body) res.body = {};
      end(function(req, res, next) {
        if(typeof res.body == 'object') {
          // serialize it as json
          res.body = JSON.stringify(res.body);
        }
        next();
      })
      next();
    })
    

    mdoq.get([query], [callback])

    query Object

    An object representing a request query to be serialized as a query string.

    callback ResponseFunction(err, res)


    mdoq.post([data], [callback])

    data Object

    An object containing data to be created or inserted.

    callback ResponseFunction(err, res)


    mdoq.put([data], [callback]) or mdoq.update([data], [callback])

    data Object

    An object containing data to be updated, must contain an identifier.

    callback ResponseFunction(err, res)


    mdoq.del([data | id], [callback])

    id Object

    A unique identifier of any data to be deleted.

    data Object

    An object containing data to be deleted, must contain an identifier.

    callback ResponseFunction(err, res)


    ResponseFunction(err, body, res, req)

    err Object

    An object containing any error information. err will be undefined if an error did not occur.

    data Object

    An object containing the res.body or res.data.


    mdoq.proxy()

    returns MiddlewareFunction(req, res, next, use)

    Returns a middleware wrapping that will execute the current stack. Useful for proxying data between servers and clients. The newly created middleware will call next(err) if an err exists.

    var app = require('express').createServer();
      , db = mdoq.require('mdoq-mongodb')
      , users = db.use('/users');
      
    app.get('/users', users.proxy()); // proxy get requests to mongodb
    

    Tests

    Install the dev dependencies.

    $ npm install -d
    

    Run the tests with make.

    $ make
    

    Keywords

    none

    install

    npm i mdoq

    Downloadsweekly downloads

    15

    version

    0.9.0

    license

    none

    repository

    github.com

    last publish

    collaborators

    • avatar