Version: 2.2.0 (latest)

Upload and Download Files

You are reading the documentation for version 2 of FoalTS. Instructions for upgrading to this version are available here. The old documentation can be found here.

Files can be uploaded and downloaded using FoalTS file system. It allows you to use different types of file storage such as the local file system or cloud storage.

Configuration#

First install the package.

npm install @foal/storage

Then specify in your configuration the file storage to be used and its settings. In this example, we will use the local file system with the uploaded directory (you must create it at the root of your project).

settings:
disk:
driver: 'local'
local:
directory: 'uploaded'

File Uploads#

Files can be uploaded using multipart/form-data requests. The @ValidateMultipartFormDataBody hook parses the request body, validates the submitted fields and files and save them in streaming to your local or Cloud storage. It also provides the ability to create file buffers if you wish.

Using Buffers#

import { Context, Post } from '@foal/core';
import { ValidateMultipartFormDataBody } from '@foal/storage';
export class UserController {
@Post('/profile')
@ValidateMultipartFormDataBody({
files: {
profile: { required: true },
images: { required: false, multiple: true }
}
})
uploadProfilePhoto(ctx: Context) {
const { buffer } = ctx.request.body.files.profile;
const files = ctx.request.body.files.images;
for (const file of files) {
// Do something with file.buffer
}
}
}

The names of the file fields must be provided in the files parameter of the hook. Uploaded files which are not listed here are simply ignored.

The required parameter tells the hook if it should return a 400 - BAD REQUEST error if no file has been uploaded for the given field. In this case, the controller method is not executed.

When the upload is successful, the request body object is set with the buffer files.

Value of multipleFiles uploadedValue in the request object
false (default)Nonenull
At least oneA buffer
trueNoneAn empty array
At least oneAn array of buffers

Using Local or Cloud Storage (streaming)#

Instead of using buffers, you can also choose to save directly the file to your local or Cloud storage. To do this, you need to add the name of the target directory in your hook options. The value returned in the ctx is an object containing the relative path of the file.

With the previous configuration, this path is relative to the uploaded directory. Note that must create the uploaded/images and uploaded/images/profiles directories before you can upload a file.

import { Context, Post } from '@foal/core';
import { ValidateMultipartFormDataBody } from '@foal/storage';
export class UserController {
@Post('/profile')
@ValidateMultipartFormDataBody({
files: {
profile: { required: true, saveTo: 'images/profiles' }
}
})
uploadProfilePhoto(ctx: Context) {
const { path } = ctx.request.body.files.profile;
// images/profiles/GxunLNJu3RXI9l7C7cQlBvXFQ+iqdxSRJmsR4TU+0Fo=.png
}
}

Accessing File Metadata#

When uploading files, the browser sends additional metadata. This can be accessed in the controller method.

const file = ctx.request.body.files.profile;
// file.mimeType, ...
Property nameTypeDescription
encodingstringEncoding type of the file
filenamestring\|undefinedName of the file on the user's computer
mimeTypestringMime type of the file
pathstringPath where the file has been saved. If the saveTo option was not provided, the value is an empty string.
bufferBufferBuffer containing the entire file. If the saveTo option was provided, the value is an empty buffer.

Adding Fields#

Multipart requests can also contain non-binary fields such as a string. These fields are validated and parsed by the hook.

import { Context, Post } from '@foal/core';
import { ValidateMultipartFormDataBody } from '@foal/storage';
export class UserController {
@Post('/profile')
@ValidateMultipartFormDataBody({
fields: {
description: { type: 'string' }
},
files: {
profile: { required: true }
}
})
uploadProfilePhoto(ctx: Context) {
const { path } = ctx.request.body.files.profile;
// images/profiles/GxunLNJu3RXI9l7C7cQlBvXFQ+iqdxSRJmsR4TU+0Fo=.png
const { description } = ctx.request.body.fields;
}
}

Specifying File Limits#

Optional settings can be provided in the configuration to limit the size or number of files uploaded.

settings:
multipartRequests:
fileSizeLimit: 1024
fileNumberLimit: 4
SettingTypeDescription
fileSizeLimitnumberThe maximum file size (in bytes).
fileNumberLimitnumberThe maximum number of files (useful for multiple file fields).

File Downloads#

Files can be downloaded using the method createHttpResponse of the Disk service. The returned object is optimized for downloading a (large) file in streaming.

import { dependency, Get } from '@foal/core';
import { Disk } from '@foal/storage';
class ApiController {
@dependency
disk: Disk;
@Get('/download')
download() {
return this.disk.createHttpResponse('avatars/foo.jpg');
}
@Get('/download2')
download() {
return this.disk.createHttpResponse('avatars/foo.jpg', {
forceDownload: true,
filename: 'avatar.jpg'
});
}
}
OptionTypeDescription
forceDownloadbooleanIt indicates whether the response should include the Content-Disposition: attachment header. If this is the case, browsers will not attempt to display the returned file (e.g. with the browser's PDF viewer) and will download the file directly.
filenamestringDefault name proposed by the browser when saving the file. If it is not specified, FoalTS extracts the name from the path (foo.jpg in the example).

Usage with a Database#

This example shows how to attach a profile picture to a user and how to retrieve and update it.

Create a new directory uploaded/images/profiles at the root of your project.

user.entity.ts

import {
BaseEntity, Column, Entity, PrimaryGeneratedColumn
} from 'typeorm';
@Entity()
export class User extends BaseEntity {
@PrimaryGeneratedColumn()
id: number;
@Column()
profile: string;
}

app.controller.ts

import { Context, dependency, Get, HttpResponseNotFound, HttpResponseRedirect, HttpResponseOK, Post, render } from '@foal/core';
import { Disk, ValidateMultipartFormDataBody } from '@foal/storage';
import { User } from './entities';
// @JWTRequired OR @UseSessions
// OR a custom hook that sets Context.user.
export class AppController {
@dependency
disk: Disk;
@Post('/profile')
@ValidateMultipartFormDataBody({
files: {
profile: { required: true, saveTo: 'images/profiles' }
}
})
async uploadProfilePicture(ctx: Context<User>) {
const user = ctx.user;
if (user.profile) {
await this.disk.delete(user.profile);
}
user.profile = ctx.request.body.files.profile.path;
await user.save();
return new HttpResponseRedirect('/');
}
@Get('/profile')
async downloadProfilePicture(ctx: Context<User>) {
const { profile } = ctx.user;
if (!profile) {
return new HttpResponseNotFound();
}
return this.disk.createHttpResponse(profile);
}
@Get('/')
index() {
return render('./templates/index.html');
}
}

templates/index.html

<!DOCTYPE html>
<html>
<body>
<img src="/profile">
<form action="/profile" method="post" enctype="multipart/form-data">
<input type="file" name="profile">
<input type="submit" value="Upload image" name="submit">
</form>
</body>
</html>

Static Files#

Static files, such as HTML, CSS, images, and JavaScript, are served by default from the public directory.

Static directory#

If necessary, this directory can be modified using the configuration key settings.staticPath.

settings:
staticPath: assets

Virtual prefix path#

In case you need to add a virtual prefix path to your static files, you can do so with the staticPathPrefix configuration key.

settings:
staticPathPrefix: /static

Example | Static file | URL path with no prefix | URL path with the prefix /static | | --- | --- | --- | | index.html | / and /index.html | /static and /static/index.html | | styles.css | /styles.css | /static/styles.css | | app.js | /app.js | /static/app.js |