Upload & Download Files
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.
#
ConfigurationFirst install the package.
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" %}
{% endcode-tabs-item %} {% code-tabs-item title="JSON" %}
{% endcode-tabs-item %} {% code-tabs-item title=".env or environment variables" %}
{% endcode-tabs-item %} {% endcode-tabs %}
#
File UploadsThis technique is available in Foal v1.7 onwards.
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 BuffersThe 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 theuploaded/images
anduploaded/images/profiles
directories before you can upload a file.
#
Adding FieldsMultipart requests can also contain non-binary fields such as a string. These fields are validated and parsed by the hook.
#
Specifying File LimitsOptional settings can be provided in the configuration to limit the size or number of files uploaded.
{% code-tabs %} {% code-tabs-item title="YAML" %}
{% endcode-tabs-item %} {% code-tabs-item title="JSON" %}
{% endcode-tabs-item %} {% code-tabs-item title=".env or environment variables" %}
{% 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 DownloadsThis technique is available in Foal v1.6 onwards.
Files can be downloaded using the method createHttpResponse
of the Disk
service. The returned object is optimized for downloading a (large) file in streaming.
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 DatabaseThis 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
app.controller.ts
templates/index.html
#
Static FilesStatic files, such as HTML, CSS, images, and JavaScript, are served by default from the public
directory.
#
Static directoryIf necessary, this directory can be modified using the configuration key settings.staticPath
.
{% code-tabs %} {% code-tabs-item title="YAML" %}
{% endcode-tabs-item %} {% code-tabs-item title="JSON" %}
{% endcode-tabs-item %} {% code-tabs-item title=".env or environment variables" %}
{% endcode-tabs-item %} {% endcode-tabs %}
#
Virtual prefix pathIn 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" %}
{% endcode-tabs-item %} {% code-tabs-item title="JSON" %}
{% endcode-tabs-item %} {% code-tabs-item title=".env or environment variables" %}
{% 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
|
#
Deprecated componentscreateHttpResponseFile
function#
The Deprecated since v1.6. Use the method
createHttpResponseFile
of theDisk
service instead.
Warning: This package only allows you to download files from your local file system. It does not work with Cloud storage.
FoalTS provides the function createHttpResponseFile
to download files in the browser from the server's local file system.
Option | Type | Description |
---|---|---|
directory | string | Path of the directory where the file is located (e.g. uploaded/ ). |
file | string | Name of the file with its extension (e.g. report.pdf ). If the string provided is a path (e.g. downloaded/report.pdf ), then Foal will automatically extract the filename (i.e. report.pdf ). |
forceDownload (optional) | 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 (optional) | string | Default name proposed by the browser when saving the file. If it is not specified, FoalTS extracts the name from the file option. |
@foal/formidable
package#
The Deprecated since v1.7. Use the
@ValidateMultipartFormDataBody
hook instead.
Warning: This package only allows you to upload files to your local file system. It does not work with Cloud storage.
You can upload files to your local file system using the library formidable. It will automatically parse the incoming form and save the submitted file(s) in the directory of your choice. A random id is generated for each saved file.
The package
@foal/formidable
is a small package that allows you to useformidable
with promises. It only has one function:parseForm
.
Assuming that the client submits a form with a field named file1
containing a file, you can save this file using IncomingForm
and parseForm
.