Contrôleurs
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.
#
DescriptionControllers are the front door of your application. They intercept all incoming requests and return the responses to the client.
The code of a controller should be concise. If necessary, controllers can delegate some tasks to services (usually the business logic).
#
Controller ArchitectureA controller is simply a class of which some methods are responsible for a route. These methods must be decorated by one of theses decorators Get
, Post
, Patch
, Put
, Delete
, Head
or Options
. They may be asynchronous.
Example:
Controllers may have sub-controllers declared in the subControllers
property.
Example:
AppController
#
The The AppController
is the main controller of your application. It is directly bound to the request handler. Every controller must be, directly or indirectly, a sub-controller of the AppController
.
Example:
#
Contexts & HTTP RequestsContext
object#
The On every request, the controller method is called with a Context
object. This context is unique and specific to the request.
It has four properties:
Name | Type | Description |
---|---|---|
request | Request | Gives information about the HTTP request. |
state | object | Object which can be used to forward data accross several hooks (see Hooks). |
user | `any | undefined` |
session | `Session | undefined` |
#
HTTP RequestsThe request
property is an ExpressJS request object. Its complete documentation can be consulted here. The below sections detail common use cases.
#
Read the BodyThe request body is accessible with the body
attribute. Form data and JSON objects are automatically converted to JavaScript objects in FoalTS.
#
Read Path ParametersPath parameters are accessible with the params
attribute.
#
Read Query ParametersQuery parameters are accessible with the query
attribute.
#
Read HeadersHeaders are accessible with the get
method.
#
Read CookiesCookies are accessible with the cookies
attribute.
#
The Controller Method ArgumentsThe path paramaters and request body are also passed as second and third arguments to the controller method.
#
HTTP ResponsesHTTP responses are defined using HttpResponse
objects. Each controller method must return an instance of this class (or a promise of this instance).
Here are subclasses that you can use:
HTTP method | Response class | Is abstract? |
---|---|---|
2XX Success | ||
2XX | HttpResponseSuccess | yes |
200 | HttpResponseOK | no |
201 | HttpResponseCreated | no |
3XX Redirection | ||
3XX | HttpResponseRedirection | yes |
301 | HttpResponseMovedPermanently | no |
302 | HttpResponseRedirect | no |
4XX Client errors | ||
4XX | HttpResponseClientError | yes |
400 | HttpResponseBadRequest | no |
401 | HttpResponseUnauthorized | no |
403 | HttpResponseForbidden | no |
404 | HttpResponseNotFound | no |
405 | HttpResponseMethodNotAllowed | no |
409 | HttpResponseConflict | no |
429 | HttpResponseTooManyRequests | no |
5XX Server errors | ||
5XX | HttpResponseServerError | yes |
500 | HttpResponseInternalServerError | no |
501 | HttpResponseNotImplemented | no |
Most of these responses accept a body
at instantiation. It can be a Buffer
object, a string, an object, a number, an array, or even a Node.JS stream.
Example with a body
In case the body parameter is a stream, you must specify it using the stream
option.
Example with a Node.JS stream as body
The
HttpResponseServerError
constructor also accepts two other options: aContext
object and an error.Example
#
Adding HeadersExample
#
Adding CookiesExample with no cookie directives
Example with cookie directives
The
maxAge
cookie directive defines the number of seconds until the cookie expires.
#
Testing ControllersA controller is a simple class and so can be tested as is. Note that hooks are ignored upon testing.
api.controller.ts (example)
api.controller.spec.ts (example)
Due to the way packages are managed by npm, you should always use
isHttpResponseOK(response)
rather thanresponse instanceof HttpResponseOK
to avoid reference bugs.
#
Inheriting ControllersExample:
You can also override foo
. If you don't add a Get
, Post
, Patch
, Put
, Delete
, Head
or Options
decorator then the parent path and HTTP method are used. If you don't add a hook, then the parent hooks are used. Otherwise they are all discarded.