Almacenamiento Local y en el Cloud
FoalTS provides its own file system for reading, writing and deleting files locally or in the Cloud. Thanks to its unified interface, you can easily choose different storage for each of your environments. This is especially useful when you're moving from development to production.
For example, when coding the application locally, you can use the file system of your operating system. Then, when deploying the application to staging or production, you can change the configuration to use AWS S3. Regardless of the storage chosen in the background, the code remains the same. Only the configuration changes.
Using FoalTS' file system has many other advantages as well:
- It can generate a unique random name when saving a new file (with the ability to add an extension if necessary).
- File contents can be managed using buffers or streams.
- Stream errors are correctly handled to avoid crashing the server.
- Not found errors are unified with a single
FileDoesNotExist
error. - FoalTS' file system can generate an
HttpResponse
to correctly download (large) files to the browser.
Configuration
First install the package.
npm install @foal/storage
Next, you will need to provide the name of the storage to be used with the configuration key setings.disk.driver
. In the case of the local filesystem, this is local
. In other cases, an additional package must be installed. Then the name to be provided is the name of the package.
Example
settings:
disk:
driver: local
Local storage
The name of the directory where the files are located is specified with the configuration key settings.disk.local.directory
.
- YAML
- JSON
- JS
settings:
disk:
driver: 'local'
local:
directory: 'uploaded'
{
"settings": {
"disk": {
"driver": "local",
"local": {
"directory": "uploaded"
}
}
}
}
module.exports = {
settings: {
disk: {
driver: "local",
local: {
directory: "uploaded"
}
}
}
}
AWS S3
AWS storage requires the installation of an additional package.
npm install @foal/aws-s3
The bucket name is specified with the settings.disk.s3.bucket
configuration key.
The region is specified with the settings.aws.region
configuration key or using AWS traditional technique.
AWS credentials are specified with the configuration keys settings.aws.accessKeyId
and settings.aws.secretAccessKey
or using AWS traditional techniques.
- YAML
- JSON
- JS
settings:
aws:
region: zzz
accessKeyId: xxx
secretAccessKey: yyy
disk:
driver: '@foal/aws-s3'
s3:
bucket: 'uploaded'
{
"settings": {
"aws": {
"region": "zzz",
"accessKeyId": "xxx",
"secretAccessKey": "yyy"
},
"disk": {
"driver": "@foal/aws-s3",
"s3": {
"bucket": "uploaded"
}
}
}
}
module.exports = {
settings: {
aws: {
region: "zzz",
accessKeyId: "xxx",
secretAccessKey: "yyy"
},
disk: {
driver: "@foal/aws-s3",
s3: {
bucket: "uploaded"
}
}
}
}
Additional options
Key name | Type | Description |
---|---|---|
settings.disk.s3.serverSideEncryption | 'AES256'|'aws:kms' | Enables server-side encryption with SSE-S3 or SSE-KMS. |
DigitalOcean
DigitalOcean Spaces are compatible with AWS S3 API, so you can use the @foal/aws-s3
package to connect to this storage.
npm install @foal/aws-s3
The only difference is the configuration key settings.aws.endpoint
, which is mandatory and requires the value ${REGION}.digitaloceanspaces.com
.
Read, Write and Delete Files
FoalTS file system is accessible via the Disk
service. It contains all the methods for reading, writing and deleting files.
Read files
Files can be read using the asynchronous read
method. It returns the size of the file as well as its contents in the form of a buffer or a readable stream. If the file does not exist, a FileDoesNotExist
error is rejected.
import { dependency } from '@foal/core';
import { Disk } from '@foal/storage';
class FileService {
@dependency
disk: Disk;
async readFile() {
const { file, size } = await this.disk.read('avatars/xxx.jpg', 'buffer');
// ...
}
async readFile2() {
const { file, size } = await this.disk.read('avatars/xxx.jpg', 'stream');
// ...
}
}