Version 1.0.0
What's new?
Finally the version 1 of FoalTs is out! This means that from now on:
- the architecture of the framework is stable,
- and features are production-ready.
This new version comes with hundreds of new lines of documentation and offers many new features:
- The session authentication system has been refactored so that we can build any kind of apps (API, SPA+API, Mobile+API, Regular Web Apps) without the difficulties that we usually have to deal with with sessions (SPA, hot reloading, serverless deployments, etc)
- VSCode debugger can be used when running unit or e2e tests.
- New functions allow us to generate tokens when we need to (password reset, ).
- Hooks can be merged into one single.
- All Express-compatible template engines are now supported.
- We can generate OpenAPI spec from the built-in hooks (
JWTRequired
,ValidateBody
,TokenRequired
, etc). - Hooks can access controller properties facilitating code reuse with inheritance.
Features (formal)
- Be able to run unit & e2e tests with VSCode debugger (issue: #386) (PR: #444).
- Infer OpenAPI specification from built-in hooks (
ValidateXXX
,JWTRequired
, etc) (issues: #423, #424) (PR: #454) - Refactor the session system and introduce the authentication tokens (issue: #451) (PR: #456).
- Have functions to generate and verify tokens (issue: #464) (PR: #456).
- Be able to group multiple hooks into one (issue: #446) (PR: #453)
- Implement the changes of version 1.0.0 (issue: #431) (PRs: #452, #465).
- Make the hooks and open api decorators have access to the controller instance (issue: #459) (PR: #466)
- Support Express template engines (issue: #445) (PR: #465)
- Simplify hook post functions (PR: #466)
How to Upgrade to Version 1
Depending on your application, upgrading your code to version 1 should take between 15 minutes and 1 hour. Most applications are only concerned by a limited number of the points mentioned below.. As we are now on version 1, this the last major upgrade that you'll face.
If you have difficulties to upgrade to version 1, feel free to open an issue. I'll be happy to help!
Feel free to open an issue, if you have trouble upgrading to version 1. I'll be happy to help!
Mandatory
Don't be afraid.
npm install @foal/core@1 # and @foal/typeorm@1, @foal/jwt@1, etc. if it applies.
-
The function
encryptPassword
has been renamed tohashPassword
. -
The configuration key
settings.staticUrl
has been renamed tosettings.staticPath
.If you created your project with
foal createapp <name>
, openconfig/default.json
and rename the key as follows:{ "settings": { "staticPath": "public/" ... } ... }
If you created your project with
foal createapp <name> --yaml
, openconfig/default.yml
and rename the key as follows:settings: staticPath: public/ ... ...
-
If you use Server-Side Rendering, the function
render
now returns aPromise<HttpResponseOK>
instead of anHttpResponseOK
object. In most cases, it does not change anything to your code. The below example still work in version 1.class ViewController { @Get('/') index() { return render('./templates/index.html', { name: 'Hello!' }, __dirname) } }
If you use
@foal/ejs
, uninstall the package and install directlyejs
instead.npm uninstall @foal/ejs npm install ejs
Then specify the name of the template engine in your configuration.
Example with config/default.json
{ "settings": { "templateEngine": "ejs" ... } ... }
Example with config/default.yml
settings: templateEngine: "ejs" ... ...
-
If you use cookies, the
maxAge
directive is now the number of seconds until the cookie expires (it was previously the number of milliseconds).// Before const response = new HttpResponseOK(); response.setCookie('my-cookie-name', 'my-cookie-value', { maxAge: 60000 }) // After const response = new HttpResponseOK(); response.setCookie('my-cookie-name', 'my-cookie-value', { maxAge: 60 })
-
If you provide your own express instance to
createApp
, thecreateApp
function now accepts only two parameters.// Before const app = createApp(AppController, { /* ... */ }, myExpressApp); // After const app = createApp(AppController, myExpressApp);
-
If you use hook post functions (which the case if you enabled CORS), their interface has been simplified. From now on, they only accept one parameter: the response object.
CORS example
// Before @Hook(() => (ctx, services, response) => { response.setHeader('Access-Control-Allow-Origin', '*'); }) export class ApiController { // ... } // After @Hook(() => response => { response.setHeader('Access-Control-Allow-Origin', '*'); }) export class ApiController { // ... }
-
If you call directly the functions
getApiComponents
orgetApiCompleteOperation
(very unlikely), they now accept 2-3 parameters:// Before getApiComponents(Foobar); getApiComponents(Foobar, 'foo'); // After getApiComponents(Foobar, new Foobar()); getApiComponents(Foobar, new Foobar(), 'foo');
-
If you use the hooks
@ValidateBody
,@ValidateQuery
,@ValidateParams
,@ValidateCookies
, their HTTP responses are now more detailed.Example of HTTP response body for
@ValidateParams
// Before [ // ... ] // After { "pathParams": [ // ... ] }
-
If you use sessions or authentication with sessions (
@LoginRequired
,@LoginOptional
), go to the appendix Sessions below. -
If you use cookies and the CSRF protection,
go to the appendix CSRF below.
Recommended
Previous versions of FoalTS used a ormconfig.json
or ormcofing.yml
file to specify the database credentials and the configuration of TypeORM.
However, this had some disadvantages:
- It was difficult to provide database credentials using environment variables. We were stuck with names such as
TYPEORM_USERNAME
orTYPEORM_PASSWORD
while most cloud providers use a different naming:DATABASE_PASSWORD
,RDS_USERNAME
, etc. - It was difficult to use a different database per environment. For example, it is very common to use different databases for development and testing. When running tests, we usually delete all existing data in the database, while when we run the server under development, we want the data from the last launch to be back.
This is why new versions of FoalTS use an ormconfig.js
file along with the Config
class (see example below). In this way, we can configure different configurations per environment (with config/
files) and use custom environment variable in ormconfig.js
(RDS_USERNAME
, etc).
I recommend that you migrate to this new configuration because it is used by default in new projects and in the new documentation.
In addition, new projects generated by FoalTS will not use the synchronize
option by default. This option recreated the database schema each time the application was launched. This is very convenient during prototyping because we don't need to create and run migrations every time we modify a model. However, this use is considered unsafe and can erase data from the database by mistake (which we do NOT want in production).
This is why new projects disable this option by default (except during testing). As a replacement, developpers must generate and run migrations each time an entity is modified. It is a little annoying but more secure. The get started tutorials will explain how migrations work and how to use them.
Example with SQLite
ormconfig.js (it replaces ormconfig.js and ormconfig.yml)
const { Config } = require('@foal/core');
module.exports = {
type: "sqlite",
database: Config.get('database.database'),
dropSchema: Config.get('database.dropSchema', false),
entities: ["build/app/**/*.entity.js"],
migrations: ["build/migrations/*.js"],
cli: {
migrationsDir: "src/migrations"
},
synchronize: Config.get('database.synchronize', false)
}
config/default.yml
port: 3001
settings:
...
database:
database: './db.sqlite3'
config/default.json
{
"port": 3001,
"settings": {
...
},
"database": {
"database": "./db.sqlite3"
}
}
config/test.yml
database:
database: './test_db.sqlite3'
dropSchema: true
synchronize: true
config/test.json
{
"database": {
"database": "./test_db.sqlite3",
"dropSchema": true,
"synchronize": true
}
}
Note: the tests generated by
foal g rest-api
assume that you use this new configuration.
Optional
-
If you have been using JWT so far to manage authentication and find it difficult, then take a look at the new Session Tokens.
-
If you do not use
Permission
s orGroup
s, i.e your classUser
does not extendUserWithPermissions
, you can remove the shell scriptscreate-perm.ts
andcreate-group.ts
from the directorysrc/scripts
. -
If you do not use Server-Side Rendering with EJS, you can uninstall the
@foal/ejs
package from your application.npm uninstall @foal/ejs
-
HttpResponse.setHeader
andHttpResponse.setCookie
now returnsthis
. So the below example can be refactored as follows to reduce the amount of code.class ApiController { @Get('/products') readProducts() { // Before const response = new HttpResponseOK(); response.setHeader('XXX', 'my header value'); response.setCookie('XXX', 'my cookie value'); return response; // Possible refactoring after return new HttpResponseOK() .setHeader('XXX', 'my header value') .setCookie('XXX', 'my cookie value'); } }
Appendices
Sessions
In version 1, the session system has been redesigned to do less magic and to allow developpers to build any kind of applications using sessions (SPA, Mobile, Regular Web Applications).
-
Remove the ExpressJS store from your file
src/index.ts
.Before
// ... import * as sqliteStoreFactory from 'connect-sqlite3'; // ... async function main() { // ... const app = createApp(AppController, { store: session => new (sqliteStoreFactory(session))({ db: 'db.sqlite3' }) }); // ... } main();
After
// ... async function main() { // ... const app = createApp(AppController); // ... } main();
npm uninstall connect-sqlite3
In the new version, FoalTS only supports Redis and SQL databases for session storage. If you need more option, feel free to open an issue on Github.
-
Replace
@LoginRequired({ user: xxx })
with@TokenRequired({ user: xxx, store: TypeORMStore, cookie: true })
.Before
import { LoginRequired } from '@foal/core'; import { fetchUser } from '@foal/typeorm'; import { User } from '../entities'; @LoginRequired({ user: fetchUser(User) }) export class ApiController { // ... }
After
import { TokenRequired, TypeORMStore } from '@foal/core'; import { fetchUser } from '@foal/typeorm'; import { User } from '../entities'; @TokenRequired({ store: TypeORMStore, user: fetchUser(User), cookie: true }) export class ApiController { // ... }
-
In the same way, replace
@LoginOptional({ user: xxx })
with@TokenOptional({ user: xxx, store: TypeORMStore, cookie: true })
. -
Open
config/default.json
(orconfig/default.yml
) and replace the session settings with the following:Before
{ "settings": { ... "session": { "cookie": { "path": "/" }, "resave": false, "saveUninitialized": false, "secret": "my-secret" } }, ... }
After
{ "settings": { ... "session": { "cookie": { "path": "/" }, "secret": "my-secret" } }, ... }
-
Open
config/production.json
(orconfig/production.yml
) and replace the session settings with the following:Before
{ "settings": { "session": { "cookie": { "httpOnly": true, "maxAge": 3600000, "sameSite": "lax", "secure": true }, "name": "id" } } }
After
{ "settings": { "session": { "cookie": { "httpOnly": true, "maxAge": 3600, "sameSite": "lax", "secure": true, "name": "id" } } } }
-
If you use
ctx.request.session
, update your code as follows:// Before const x = ctx.request.session.x; ctx.request.session.y = 1; // After const x = ctx.session.get('x'); ctx.session.set('y', 1);
-
Update your "login and logout controller" as follows:
Before
export class AuthController { @Post('/login') // ... async login(ctx: Context) { // ... logIn(ctx, user); return new HttpResponseRedirect('/'); } @Get('/logout') logout(ctx) { logOut(ctx); return new HttpResponseRedirect('/signin'); } }
After
import { Context, dependency, Post, removeSessionCookie, Session, setSessionCookie, TokenRequired } from '@foal/core'; import { TypeORMStore } from '@foal/typeorm'; export class AuthController { @dependency store: TypeORMStore; @Post('/login') // ... async login(ctx: Context) { // ... const session = await this.store.createAndSaveSessionFromUser(user); const response = new HttpResponseRedirect('/'); setSessionCookie(response, session.getToken()); return new HttpResponseRedirect('/'); } @Post('/logout') @TokenRequired({ store: TypeORMStore, cookie: true, extendLifeTimeOrUpdate: false }) async logout(ctx: Context<any, Session>) { await this.store.destroy(ctx.session.sessionID); const response = new HttpResponseRedirect('/login'); removeSessionCookie(response); return response; } }
CSRF
-
Install the package
@foal/csrf
.npm install @foal/csrf
-
If you use sessions, add the hook
@CsrfTokenRequired()
after@TokenRequired(...)
Example
import { CsrfTokenRequired } from '@foal/csrf'; @TokenRequired({ cookie: true, /* ... */ }) @CsrfTokenRequired() export class ApiController { // ... }
-
OR if you use double submit cookie technique, add the hook
@CsrfTokenRequired({ doubleSubmitCookie: true })
on the protected routes.Example
import { CsrfTokenRequired } from '@foal/csrf'; // Ex: @JWTRequired() @CsrfTokenRequired({ doubleSubmitCookie: true }) export class ApiController { }
-
The CSRF configuration has changed from
settings: csrf: true
to
settings: csrf: enabled: true
-
Replace
ctx.request.csrfToken()
withgetCsrfToken(ctx.session)
if you use sessions orgetCsrfToken()
if you use double submit cookie technique.Before
export class PageController { @Get('/home') home(ctx: Context) { return render( './templates/index.html', { csrfToken: ctx.request.csrfToken() } , __diname ); } }
After
import { getCsrfToken } from '@foal/csrf'; @TokenRequired(/* ... */) // Only if you use sessions export class PageController { @Get('/home') home(ctx: Context) { return render( './templates/index.html', { csrfToken: getCsrfToken(ctx.session) } , __diname ); } }