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

• Install
• Usage
• Components
• Tests
• Conventions
• Contributors
• Credits
• License

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
• error-handler
• knex
• logger
• mongo
• mongoose-plugin
• server
• sessions
• settings
• update-notifier

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 https://github.com/yeoman/update-notifier/issues/25

View source

Tests

npm install -d
npm test

Conventions

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

Contributors

• Nick Baugh niftylettuce@gmail.com
• Adnan Ibrišimbegović adibih@gmail.com
• Bruno Bernardino me@brunobernardino.com

Credits

• Igloo by VALÈRE DAYAN from The Noun Project
• ESKIMO IGLOO (color palette)

License

MIT