upload-and-download-files.md

Upload & 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).

{% code-tabs %} {% code-tabs-item title="YAML" %}

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

{% endcode-tabs-item %} {% code-tabs-item title="JSON" %}

{
  "settings": {
    "disk": {
      "driver": "local",
      "local": {
        "directory": "uploaded"
      }
    }
  }
}

{% endcode-tabs-item %} {% code-tabs-item title="JS" %}

module.exports = {
  settings: {
    disk: {
      driver: "local",
      local: {
        directory: "uploaded"
      }
    }
  }
}

{% endcode-tabs-item %} {% endcode-tabs %}

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 multiple	Files uploaded	Value in the request object
false (default)	None	null
	At least one	A buffer
true	None	An empty array
	At least one	An 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 name	Type	Description
encoding	string	Encoding type of the file
filename	`string	undefined`
mimeType	string	Mime type of the file
path	string	Path where the file has been saved. If the saveTo option was not provided, the value is an empty string.
buffer	Buffer	Buffer 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.

{% code-tabs %} {% code-tabs-item title="YAML" %}

settings:
  multipartRequests:
    fileSizeLimit: 1024
    fileNumberLimit: 4

{% endcode-tabs-item %} {% code-tabs-item title="JSON" %}

{
  "settings": {
    "multipartRequests": {
      "fileSizeLimit": 1024,
      "fileNumberLimit": 4,
    }
  }
}

{% endcode-tabs-item %} {% code-tabs-item title="JS" %}

module.exports = {
  settings: {
    multipartRequests: {
      fileSizeLimit: 1024,
      fileNumberLimit: 4,
    }
  }
}

{% endcode-tabs-item %} {% endcode-tabs %}

Setting	Type	Description
fileSizeLimit	number	The maximum file size (in bytes).
fileNumberLimit	number	The 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'
    });
  }

}

Option	Type	Description
forceDownload	boolean	It 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.
filename	string	Default 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.

{% code-tabs %} {% code-tabs-item title="YAML" %}

settings:
  staticPath: assets

{% endcode-tabs-item %} {% code-tabs-item title="JSON" %}

{
  "settings": {
    "staticPath": "assets"
  }
}

{% endcode-tabs-item %} {% code-tabs-item title="JS" %}

module.exports = {
  settings: {
    staticPath: "assets"
  }
}

{% endcode-tabs-item %} {% endcode-tabs %}

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.

{% code-tabs %} {% code-tabs-item title="YAML" %}

settings:
  staticPathPrefix: /static

{% endcode-tabs-item %} {% code-tabs-item title="JSON" %}

{
  "settings": {
    "staticPathPrefix": "/static"
  }
}

{% endcode-tabs-item %} {% code-tabs-item title="JS" %}

module.exports = {
  settings: {
    staticPathPrefix: "/static"
  }
}

{% endcode-tabs-item %} {% endcode-tabs %}

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