README

feathers-blob

Feathers abstract blob store service

Installation

npm install feathers-blob --save

Also install a abstract-blob-store compatible module.

API

`const BlobService = require('feathers-blob')`

`blobService = BlobService(options)`

options.Model is an instantiated interface that implements the abstract-blob-store API
options.id is a string 'key' for the blob identifier.
returnUri defaults is true, set it to false to remove it from output.
returnBuffer defaults is false , set it to true to return buffer in the output.

Tip: returnUri/returnBuffer are mutually exclusive.

If you only want a buffer output instead of a data URI on create/get operations, you need to set returnBuffer to be true, also to set retuarnUri to be false.

If you need both, use the default options, then extract the buffer from the data URI on the client-side to avoid transferring the data twice over the wire.

`blobService.create(body, params)`

where input body is an object with either:

a key uri pointing to data URI of the blob,
a key buffer pointing to raw data buffer of the blob along with its contentType (i.e. MIME type).

Optionally, you can specify in the body the blob id which can be the file path where you want to store the file, otherwise it would default to ${hash(content)}.${extension(contentType)}.

Tip: You can use feathers hooks to customize the id. You might not want the client-side to write whereever they want.

returns output 'data' of the form:

{
  [this.id]: `${hash(content)}.${extension(contentType)}`,
  uri: body.uri, // When returnUri options is set true
  buffer: body.buffer, // When returnBuffer options is set true
  size: length(content)
}

`blobService.get(id, params)`

returns output data of the same form as create.

`blobService.remove(id, params)`

Params:

Query:

VersionId (string): Version ID of document to access if using a versioned s3 bucket

Example:

blobService.get('my-file.pdf', {
  query: {VersionId: 'xslkdfjlskdjfskljf.sdjfdkjfkdjfd'},
})

Example

const { getBase64DataURI } = require('dauria');
const AWS = require('aws-sdk');
const S3BlobStore = require('s3-blob-store');
const feathers = require('@feathersjs/feathers');
const BlobService = require('feathers-blob');

const s3 = new AWS.S3({
  endpoint: 'https://{service}.{region}.{provider}.com',
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
});

const blobStore = S3BlobStore({
  client: s3,
  bucket: 'feathers-blob'
});

const blob = {
  uri: getBase64DataURI(new Buffer('hello world'), 'text/plain')
}

const app = feathers();

app.use('/upload', BlobService({
  Model: blobStore
}));

const blobService = app.service('upload');

blobService.create(blob).then(function (result) {
  console.log('Stored blob with id', result.id);
}).catch(err => {
  console.error(err);
});

Should you need to change your bucket's options, such as permissions, pass a params.s3 object using a before hook.

app.service('upload').before({
  create(hook) {
    hook.params.s3 = { ACL: 'public-read' }; // makes uploaded files public
  }
});

For a more complete example, see examples/app which can be run with npm run example.

Tests

Tests can be run by installing the node modules and running npm run test.

To test the S3 read/write capabilities set the environmental variable S3_BUCKET to the name of a bucket you have read/write access to. Enable the versioning functionality on the bucket.

License

Licensed under the MIT license.

Usage no npm install needed!