This package has been deprecated

Author message:

This package is deprecated and a better alternative has been created, please use Lad: https://lad.js.org

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
• Install
• Usage
• Components
• Tests
• Conventions
• Contributors
• Credits
• License

Sponsor

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 [e-mail]
• Adnan Ibrišimbegović [e-mail]
• Bruno Bernardino [e-mail]

Credits

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

License

MIT