@amag-ch/sap_cap_common_objectstore/README.md

NodeJS library to communicate with an objectstore

[![npm version](https://img.shields.io/npm/v/@amag-ch/sap_cap_common_objectstore?style=flat-square)](https://www.npmjs.com/package/@amag-ch/sap_cap_common_objectstore)
[![npm downloads](https://img.shields.io/npm/dm/@amag-ch/sap_cap_common_objectstore.svg?style=flat-square)](https://npm-stat.com/charts.html?package=@amag-ch/sap_cap_common_objectstore)

NodeJS library to communicate with an objectstore

## Table of Contents

- [Features](#features)
- [Installing](#installing)
- [Configuration](#configuration)
- [Implementation](#implementation)
- [License](#license)

## Features

- Fully integrated in CAP as a Service
- Support S3 objectstore and local objectstore for development testings
- Autodeletion if corresponding entity entry is been deleted (Entity which uses File)
- Autohandling streaming, if content is requested
- Testfiles possible
- Lazy deletion of objects and only executed, if transaction is successfull
- Auto configuration with cds plugin feature

## Installing

Using npm:

```bash
$ npm install @amag-ch/sap_cap_common_objectstore
```

Using yarn:

```bash
$ yarn add @amag-ch/sap_cap_common_objectstore
```

## Configuration

```json
{
    "cds": {
        "requires": {
            "objectstore": {
                "impl": "@amag-ch/sap_cap_common_objectstore",
                "kind": "objectstore"
            }
        }
    }
}
```

The name and kind must be named `objectstore`, otherwise CAP cannot inject the credentials from environment

Variant with local objectstore for development testings
```json
{
    "cds": {
        "requires": {
            "objectstore": {
                "impl": "@amag-ch/sap_cap_common_objectstore",
                "kind": "local-objectstore",
                "[production]": {
                    "kind": "objectstore",
                }
            }
        }
    }
}
```

The local objectstore is saved in folder `~/.cds-objectstore`

### Standard configuration (cds-plugin)
```json
{
    "cds": {
        "requires": {
            "objectstore": {
                "impl": "@amag-ch/sap_cap_common_objectstore",
                "kind": "local-objectstore",
                "[production]": {
                    "kind": "objectstore"
                }
            }
        }
    }
}
```

## Implementation

### Database Schema
```cds
using {amag.common.objectstore.File as File} from '@amag-ch/sap_cap_common_objectstore';

entity MyEntity {
    key ID      : UUID;
        file    : File
}

```
File is definied as Composition. Means if entry of MyEntity is been deleted, also the connected File would be deleted.
File is per default defined as attachment (`@Core.ContentDisposition.Type: 'attachment'`), but could be overwriten with own annotations.

### Service for add or read files
```js
const objectstore = await cds.connect.to('objectstore')

const ID = await objectstore.create('Any File Content', { filename: 'Testfile.txt', contentType: 'text/plain' })

const file = await objectstore.read(ID)

console.log(file.modifiedAt)

const stream = await objectstore.readContent(ID)
```

### Testing

Create a folder (e.g. `test/objectstore`) with all needed files named by ID, which is also used in `test/data/amag.common.objectstore-Files.csv`.

With `cds-plugin` mode this folder is automatically registered.

Otherwise add file `test/init.js` with following code snippet to register your folder.
```js
module.exports = async () => {
    require('@amag-ch/sap_cap_common_objectstore').testing.register(`${__dirname}/objectstore`)
}
```

## License

[MIT](LICENSE)