/igloo

Igloo is a library of components built with electrolyte to be used as building blocks for an app.

Primary LanguageJavaScriptMIT LicenseMIT

Igloo

NPM version Build Status NPM downloads Test Coverage Static Analysis MIT License Gitter

Igloo

Igloo is a library of components built with electrolyte to be used as building blocks for an app.

Need to view documentation for a given component? See Components below.

Index

Sponsor

Clevertech

Install

Please use eskimo which has igloo built-in.

However you can use igloo in your own project by installing it.

npm install -s igloo

Usage

You will need to first require('igloo'), define a "config" component, and then use electrolyte's IoC.loader method to load igloo's components ([listed below][#components]).

Note that igloo requires you to have defined a "config" component (since igloo's "setting" component requires it as a dependency). For example, Eskimo defines a "config" component here.

// boot/config.js

exports = module.exports = function() {
  return {
    defaults: {
      logger: {
        console: true,
        requests: true,
        mongo: false,
        file: false,
        hipchat: false
      },
      output: {
        handleExceptions: true,
        colorize: true,
        prettyPrint: false
      }
    },
    development: {
      server: {
        port: 3000
      }
    },
    production: {
      server: {
        port: 3080
      },
      logger: {
        requests: false
      },
      output: {
        colorize: false,
        prettyPrint: false
      }
    }
  }
}

exports['@singleton'] = true

You can have a boot/local.js with local settings if you need something unversioned (and load it when the environment is development — default).

// boot/local.js

var path = require('path')
var uploadsDir = path.join(__dirname, '..', 'uploads')
var maxAge = 30 * 24 * 60 * 60 * 1000

exports = module.exports = function() {

  return {
    uploadsDir: uploadsDir,
    server: {
      host: '0.0.0.0',
      env: 'local',
      port: 3003,
    },
    mongo: {
      dbname: 'igloo-local',
    },
    redis: {
      prefix: 'igloo-local',
      maxAge: maxAge
    }

  }

}

exports['@singleton'] = true
// app.js

var IoC = require('electrolyte')
var igloo = require('igloo')
var path = require('path')
var express = require('express')
var winstonRequestLogger = require('winston-request-logger')

IoC.loader(IoC.node(path.join(__dirname, 'boot')))
IoC.loader('igloo', igloo)

// logger component
var logger = IoC.create('igloo/logger')
logger.info('Hello world')

// settings component
var settings = IoC.create('igloo/settings')

// basic server

var app = express()

// winston request logger before everything else
// but only if it was enabled in settings
if (settings.logger.requests)
  app.use(winstonRequestLogger.create(logger))

app.get('/', function(req, res, next) {
  res.send("It's cold outside, but warm in the igloo")
})

app.listen(settings.server.port, function() {
  logger.info('Server started on port %d', settings.server.port)
})

Components

email

Returns a function which accepts templateName, locals, headers, transport, and callback arguments. This component uses

View source

// example - email

// TODO: finish this!

// mention that transport defaults to settings.email.transport

// mention that headers inherits settings.email.headers

// but only if you don't set `headers.useDefaults: false`

// note that is also uses `settings.email.templates` object
// which can have `dir` string and `options` object for node email-templates pkg

// also document about having `transport` of `settings.email.transport` be an
// actual transporter already pre-created (possibly with plugins like html-to-text)

error-handler

Returns Express route middleware for error handling.

View source

// example - error handler

var _ = require('underscore')
var errorHandler = IoC.create('igloo/error-handler')

app.post('/user', createUser, errorHandler)

// you could also do:
// app.post('/user', createUser)
// app.use(errorHandler)
// but make sure that `app.use(errorHandler)`
// is the very last route middleware to be `use`'d

function createUser(req, res, next) {

  if (!_.isString(req.body.name))
    return next({
      param: 'name',
      message: 'User name is missing'
    })

  // ... create a user in your db
  res.send('You successfully created a user')

}

knex

Returns a Knex SQL database connection using settings.knex.

View source

// example - knex

var knex = IoC.create('igloo/knex')

app.get('/users', function(req, res, next) {
  knex
    .raw('SELECT * FROM USERS LIMIT 10')
    .exec(function(err, results) {
      if (err) return next(err)
      res.send(results)
    })
})

logger

Returns a Winston logger object with pre-configured transports using settings.logger and settings.output.

View source

// example - logger

var logger = IoC.create('igloo/logger')

logger.info('Hello world')

mongo

Returns a MongoDB NoSQL connection using settings.logger, settings.output, and settings.mongo and Mongoose ORM.

TODO: Should we rename this to igloo/mongoose?

View source

// example - mongo

var validator = require('validator')
var mongoose = IoC.create('igloo/mongo')

var User = new mongoose.Schema({
  email: {
    type: String,
    required: true,
    unique: true,
    validate: validator.isEmail
  }
})

mongoose.model('User', User)

mongoose-plugin

Returns a Mongoose plugin helper for common schema additions.

View source

// example - mongoose plugin

var validator = require('validator')
var mongoose = IoC.create('igloo/mongo')
var mongoosePlugin = IoC.create('igloo/mongoose-plugin')

var User = new mongoose.Schema({
  email: {
    type: String,
    required: true,
    unique: true,
    validate: validator.isEmail
  }
})

User.plugin(mongoosePlugin)

mongoose.model('User', User)

server

Returns a function which accepts a callback argument (currently no err argument is returned when this callback function is executed). This component starts either a cluster (with one thread per CPU) or a simple single-threaded instance using app.listen. This should be used with app.phase using bootable, since bootable's "phases" (app.phase) method accepts this callback function as a standard argument when defining a "phase" (read more about bootable to understand this please). This component uses settings.logger, settings.output, and settings.server.

View source

// example - server

var bootable = require('bootable')
var express = require('express')

var app = bootable(express())

var server = IoC.create('igloo/server')
var logger = IoC.create('igloo/logger')

// this should always be the last phase
app.phase(server)

app.boot(function(err) {

  if (err) {
    logger.error(err.message)
    if (settings.showStack)
      logger.error(err.stack)
    process.exit(-1)
    return
  }

  logger.info('app booted')

})

sessions

Returns a Redis connection using settings.logger, settings.output, and settings.redis with express-session and connect-redis.

View source

// example - sessions

var session = require('express-session')
var express = require('express')

var app = express()

var sessions = IoC.create('igloo/sessions')
var settings = IoC.create('igloo/settings')

// add req.session cookie support
settings.session.store = sessions
app.use(session(settings.session))

settings

Returns a settings object using a "config" component defined and loaded by electrolyte in a location such as "boot/config" (see initial example at the top of this Readme).

For a full config example file, see Eskimo's default config.

View source

update-notifier

Returns nothing, as it is used for notifying an app of module updates using update-notifier.

TODO: Look into why this isn't working per yeoman/update-notifier#25

View source

Tests

npm install -d
npm test

Conventions

See nifty-conventions for code guidelines, general project requirements, and git workflow.

Contributors

Credits

License

MIT