sosloow / mongoose-crate

mongoose-crate

mongoose-crate is a plugin for Mongoose for attaching files to documents.

File meta data is stored in MongoDB, whereas the actual file itself is stored on the local filesystem, Amazon S3 or Google Cloud Storage. For others pull requests are gratefully accepted.

Uploaded images can optionally be passed through ImageMagick to generate one or more images (e.g. thumbnails, full size, original image, etc) before saving.

The architecture is nominally based on mongoose-attachments but that project hasn't seen updates in a while.

## Usage

The following example extends the 'Post' model to use attachments with a property called 'attachment'.

var mongoose = require('mongoose'),
  crate = require('mongoose-crate'),
  LocalFS = require('mongoose-crate-localfs')

var PostSchema = new mongoose.Schema({
  title: String
})

PostSchema.plugin(crate, {
  storage: new LocalFS({
    directory: '/path/to/storage/directory'
  }),
  fields: {
    attachment: {}
  }
})

var Post = mongoose.model('Post', PostSchema)

.. then later:

var post = new Post()
post.attach('attachment', {path: '/path/to/file'}, function(error) {
	// attachment is now attached and post.attachment is populated e.g.:
	// post.attachment.url

	// don't forget to save it..
	post.save(function(error) {
		// post is now persisted
	})
})

Arrays

Files can be stored in arrays as well as individual properties. Just specify the array property to the field definition:

var mongoose = require('mongoose'),
  crate = require('mongoose-crate'),
  LocalFS = require('mongoose-crate-localfs')

var PostSchema = new mongoose.Schema({
  title: String
})

PostSchema.plugin(crate, {
  storage: new LocalFS({
    directory: '/path/to/storage/directory'
  }),
  fields: {
    attachments: {
      array: true
    }
  }
})

var Post = mongoose.model('Post', PostSchema)

.. then later:

var post = new Post()
post.attach('attachments', {path: '/path/to/file'}, function(error) {
  // post.attachments.length == 1

  post.attach('attachments', {path: '/path/to/another/file'}, function(error) {
    // post.attachments.length == 2
  })
})

Images

See mongoose-crate-imagemagick.

Using with Express.js uploads

Assuming that the HTML form sent a file in a field called 'image':

app.post('/upload', function(req, res, next) {
  var post = new mongoose.model('Post')()
  post.title = req.body.title
  post.description = req.body.description
  post.attach('image', req.files.image, function(err) {
    if(err) return next(err)
    post.save(function(err) {
      if(err) return next(err)
      res.send('Post has been saved with file!')
    })
  })
})

Using with an stand-alone app files

var post = new mongoose.model('Post')()
post.title = 'Title of the Post'
post.description = 'Description of the Post'
post.attach('image', '/path/to/the/file.png', function(err) {
    if(err) return next(err)
    post.save(function(err) {
      if(err) return next(err)
      console.log('Post has been Saved with file')
    })
})

Metadata

Basic meta data is captured about uploaded files.

Example:

{
  "name" : "dragon.png",
  "size" : 26887,
  "type": "image/png",
  "url" : "http://my_bucket.s3.amazonaws.com/folder/4fbaaa31db8cec0923000019-medium.png"
}

Plugins can add extra meta data. E.g. mongoose-crate-imagemagick adds width, height, etc.

## Deletes and updates

If you delete a model, any attached files will be removed along with it (with one caveat, see Schema methods vs Queries below). Similarly, if you attach a file to a field that already has an attachment, the old file will be deleted before the new one is added.

For attachment arrays, when the model is saved, any attachments that are no longer in the array will have their files removed.

Schema methods vs Queries

Removal of files happens via middleware - if you use findById, findOne or anything else that returns a Query and call methods on that query, middleware is not executed. See the Mongoose middleware docs for more.

In short, do this sort of thing:

MySchema.remove({...}, callback)

or this:

MySchema.findOne({...}, function(err, doc) {
  doc.remove(callback)
})

..but not this:

MySchema.findOne({...}).remove(callback)

Array attachment deletion

var mongoose = require('mongoose'),
  crate = require('mongoose-crate'),
  LocalFS = require('mongoose-crate-localfs')

var MySchema = new mongoose.Schema({
  name: {
    type: String,
    required: true
  }
})

MySchema.plugin(crate, {
  storage: new LocalFS({
    directory: '/path/to/storage/directory'
  }),
  fields: {
    files: {
      array: true
    }
  }
})

// ...

var model = new MySchema()
model.name = 'hello'
model.attach('files', {
    path: file
}, callback)

// some time later remove one of the array entries

model.files.pop()
model.save()

Non array attachment deletion

var mongoose = require('mongoose'),
  crate = require('mongoose-crate'),
  LocalFS = require('mongoose-crate-localfs')

var MySchema = new mongoose.Schema({
  name: {
    type: String,
    required: true
  }
})

MySchema.plugin(crate, {
  storage: new LocalFS({
    directory: '/path/to/storage/directory'
  }),
  fields: {
    file: {}
  }
})

// ...

var model = new MySchema()
model.name = 'hello'
model.attach('file', {
    path: file
}, callback)

// some time later delete the file

model.file = null
model.save()