# feathers-blob

> Feathers blob service

Latest version **2.6.0** (published 2021-06-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install feathers-blob
pnpm add feathers-blob
yarn add feathers-blob
bun add feathers-blob
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.6.0 |
| Published | 2021-06-20 |
| First published | 2016-02-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >= 6 |
| Dependencies | 7 |
| Unpacked size | 33 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 93 |
| Author | Feathers contributors |
| Maintainers | daffl, ekryski, claustres |
| Keywords | feathers, feathers-plugin, blob, abstract-blob-store, fs, s3, file, files, binary |

## Links

- npm: https://www.npmjs.com/package/feathers-blob
- Repository: https://github.com/feathersjs-ecosystem/feathers-blob
- Issues: https://github.com/feathersjs-ecosystem/feathers-blob/issues
- npm.io page: https://npm.io/package/feathers-blob

## Dependencies (7)

- [debug](https://npm.io/package/debug.md) ^4.0.0
- [from2](https://npm.io/package/from2.md) ^2.1.1
- [dauria](https://npm.io/package/dauria.md) ^2.0.0
- [uberproto](https://npm.io/package/uberproto.md) ^2.0.0
- [mime-types](https://npm.io/package/mime-types.md) ^2.1.10
- [concat-stream](https://npm.io/package/concat-stream.md) ^2.0.0
- [@feathersjs/errors](https://npm.io/package/@feathersjs/errors.md) ^4.3.0

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 2.6.0 (latest) — 2021-06-20
- 2.5.0 — 2021-04-25
- 2.4.0 — 2021-04-15
- 2.3.0 — 2020-10-04
- 2.2.0 — 2019-12-18
- 2.1.0 — 2019-03-09
- 2.0.1 — 2018-06-03
- 2.0.0 — 2018-03-09
- 1.5.0 — 2018-03-07
- 1.4.1 — 2018-03-02
- 1.4.0 — 2018-02-16
- 1.3.1 — 2017-06-30
- 1.3.0 — 2017-06-21
- 1.2.0 — 2016-08-18
- 1.1.0 — 2016-06-17
- … 4 more at https://npm.io/package/feathers-blob/versions

## README

# feathers-blob

[![Node.js CI](https://github.com/feathersjs-ecosystem/feathers-blob/actions/workflows/node.js.yml/badge.svg)](https://github.com/feathersjs-ecosystem/feathers-blob/actions/workflows/node.js.yml)
[![Dependency Status](https://img.shields.io/david/feathersjs-ecosystem/feathers-blob.svg?style=flat-square)](https://david-dm.org/feathersjs-ecosystem/feathers-blob)
[![Download Status](https://img.shields.io/npm/dm/feathers-blob.svg?style=flat-square)](https://www.npmjs.com/package/feathers-blob)

> [Feathers](http://feathersjs.com) [`abstract blob store`](https://github.com/maxogden/abstract-blob-store) service

## Installation

```shell
npm install feathers-blob --save
```

Also install a [`abstract-blob-store` compatible module](https://github.com/maxogden/abstract-blob-store#some-modules-that-use-this).


## API

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

### `blobService = BlobService(options)`

- `options.Model` is an instantiated interface [that implements the `abstract-blob-store` API](https://github.com/maxogden/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](https://en.wikipedia.org/wiki/Data_URI_scheme) of the blob,
* a key `buffer` pointing to [raw data buffer](https://nodejs.org/api/buffer.html) 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:

```js
{
  [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: 

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

## Example

```js
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](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property), such as permissions, pass a `params.s3` object using a before hook.

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

For a more complete example, see [examples/app](./examples/app.js) 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

Copyright (c) 2018

Licensed under the [MIT license](LICENSE).

---
_Source: https://npm.io/package/feathers-blob · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._