@lykmapipo/gridfs-stream

    1.2.0 • Public • Published

    gridfs-stream

    Easily stream files to and from MongoDB GridFS.

    Please note

    gridfs-stream v1.x uses Stream2 API from nodejs v0.10 (and the mongodb v2.x driver). It provides more robust and easier to use streams. If for some reason you need nodejs v0.8 streams, please switch to the gridfs-stream 0.x branch

    Description

    var mongo = require('mongodb');
    var Grid = require('gridfs-stream');
     
    // create or use an existing mongodb-native db instance
    var db = new mongo.Db('yourDatabaseName', new mongo.Server("127.0.0.1", 27017));
    var gfs = Grid(db, mongo);
     
    // streaming to gridfs
    var writestream = gfs.createWriteStream({
        filename: 'my_file.txt'
    });
    fs.createReadStream('/some/path').pipe(writestream);
     
    // streaming from gridfs
    var readstream = gfs.createReadStream({
      filename: 'my_file.txt'
    });
     
    //error handling, e.g. file does not exist
    readstream.on('error', function (err) {
      console.log('An error occurred!', err);
      throw err;
    });
     
    readstream.pipe(response);

    Alternatively you could read the file using an _id. This is often a better option, since filenames don't have to be unique within the collection. e.g.

    var readstream = gfs.createReadStream({
      _id: '50e03d29edfdc00d34000001'
    });
     

    Created streams are compatible with other Node streams so piping anywhere is easy.

    install

    npm install gridfs-stream
    

    use

    var mongo = require('mongodb');
    var Grid = require('gridfs-stream');
     
    // create or use an existing mongodb-native db instance.
    // for this example we'll just create one:
    var db = new mongo.Db('yourDatabaseName', new mongo.Server("127.0.0.1", 27017));
     
    // make sure the db instance is open before passing into `Grid`
    db.open(function (err) {
      if (err) return handleError(err);
      var gfs = Grid(db, mongo);
     
      // all set!
    })

    The gridfs-stream module exports a constructor that accepts an open mongodb-native db and the mongodb-native driver you are using. The db must already be opened before calling createWriteStream or createReadStream.

    Now we're ready to start streaming.

    createWriteStream

    To stream data to GridFS we call createWriteStream passing any options.

    var writestream = gfs.createWriteStream([options]);
    fs.createReadStream('/some/path').pipe(writestream);

    Options may contain zero or more of the following options, for more information see GridStore:

    {
        _id: '50e03d29edfdc00d34000001', // a MongoDb ObjectId
        filename: 'my_file.txt', // a filename
        mode: 'w', // default value: w
     
        //any other options from the GridStore may be passed too, e.g.:
     
        chunkSize: 1024,
        content_type: 'plain/text', // For content_type to work properly, set "mode"-option to "w" too!
        root: 'my_collection',
        metadata: {
            ...
        }
    }

    Events

    The writeStream is a fully compliant Stream2 Writable Stream, it emits all the associated events (drain, finish, pipe, unpipe, error), as well as additional special events (open, close).

    finish is emitted after the file has been completely written to GridFS.

    open is emitted after the GridStore is successfully opened.

    close is emitted after the GridStore is successfully closed, which means the file is fully written to GridFS, and the file object is passed as the first argument.

    writestream.on('close', function (file) {
      // do something with `file`
      console.log(file.filename);
    });

    Methods

    The writeStream has additional methods:

    destroy([err]): Destroy the writeStream as soon as possible: stop writing incoming data, close the _store. An error event will be emitted, as well as a close event. It's up to you to cleanup the GridStore if it's not desired to keep half written files in GridFS (the close event returns a GridStore file which can be used to delete the file, or mark it failed).

    createReadStream

    To stream data out of GridFS we call createReadStream passing any options, at least an _id or filename.

    var readstream = gfs.createReadStream(options);
    readstream.pipe(response);

    See the options of createWriteStream for more information.

    To get partial data with createReadStream, use range option. e.g.

    var readstream = gfs.createReadStream({
      _id: '50e03d29edfdc00d34000001',
      range: {
        startPos: 100,
        endPos: 500000
      }
    });

    removing files

    Files can be removed by passing options (at least an _id or filename) to the remove() method.

    gfs.remove(options, function (err, gridStore) {
      if (err) return handleError(err);
      console.log('success');
    });

    See the options of createWriteStream for more information.

    check if file exists

    Check if a file exist by passing options (at least an _id or filename) to the exist() method.

    gfs.exist(options, function (err, found) {
      if (err) return handleError(err);
      found ? console.log('File exists') : console.log('File does not exist');
    });

    See the options of createWriteStream for more information.

    accessing file metadata

    All file meta-data (file name, upload date, contentType, etc) are stored in a special mongodb collection separate from the actual file data. This collection can be queried directly:

      var gfs = Grid(conn.db);
      gfs.files.find({ filename: 'myImage.png' }).toArray(function (err, files) {
        if (err) ...
        console.log(files);
      })

    Alternatively you can use the gfs.findOne-shorthand to find a single file

      gfs.findOne({ _id: '54da7b013706c1e7ab25f9fa'}, function (err, file) {
        console.log(file);
      });

    using with mongoose

    var mongoose = require('mongoose');
    var Grid = require('gridfs-stream');
     
    var conn = mongoose.createConnection(..);
    conn.once('open', function () {
      var gfs = Grid(conn.db, mongoose.mongo);
     
      // all set!
    })

    You may optionally assign the driver directly to the gridfs-stream module so you don't need to pass it along each time you construct a grid:

    var mongoose = require('mongoose');
    var Grid = require('gridfs-stream');
    Grid.mongo = mongoose.mongo;
     
    var conn = mongoose.createConnection(..);
    conn.once('open', function () {
      var gfs = Grid(conn.db);
     
      // all set!
    })

    LICENSE

    Install

    npm i @lykmapipo/gridfs-stream

    DownloadsWeekly Downloads

    120

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    84.7 kB

    Total Files

    13

    Last publish

    Collaborators

    • lykmapipo