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.

1. The function encryptPassword has been renamed to hashPassword.

2. The configuration key settings.staticUrl has been renamed to settings.staticPath.

   If you created your project with foal createapp <name>, open config/default.json and rename the key as follows:

   {
     "settings": {
       "staticPath": "public/"
       ...
     }
     ...
   }

   If you created your project with foal createapp <name> --yaml, open config/default.yml and rename the key as follows:

   settings:
     staticPath: public/
     ...
   ...

3. If you use Server-Side Rendering, the function render now returns a Promise<HttpResponseOK> instead of an HttpResponseOK 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 directly ejs 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"
     ...
   ...

4. 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 })

5. If you provide your own express instance to createApp, the createApp function now accepts only two parameters.

   // Before
   const app = createApp(AppController, { /* ... */ }, myExpressApp);
   
   // After
   const app = createApp(AppController, myExpressApp);

6. 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 {
     // ...
   }

7. If you call directly the functions getApiComponents or getApiCompleteOperation (very unlikely), they now accept 2-3 parameters:

   // Before
   getApiComponents(Foobar);
   getApiComponents(Foobar, 'foo');
   
   // After
   getApiComponents(Foobar, new Foobar());
   getApiComponents(Foobar, new Foobar(), 'foo');

8. 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": [
       // ...
     ]
   }

9. If you use sessions or authentication with sessions (@LoginRequired, @LoginOptional), go to the appendix Sessions below.

10. 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 or TYPEORM_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

1. If you have been using JWT so far to manage authentication and find it difficult, then take a look at the new Session Tokens.

2. If you do not use Permissions or Groups, i.e your class User does not extend UserWithPermissions, you can remove the shell scripts create-perm.ts and create-group.ts from the directory src/scripts.

3. If you do not use Server-Side Rendering with EJS, you can uninstall the @foal/ejs package from your application.

   npm uninstall @foal/ejs
   

4. HttpResponse.setHeader and HttpResponse.setCookie now returns this. 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).

1. 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.

2. 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 {
     // ...
   }

3. In the same way, replace @LoginOptional({ user: xxx }) with @TokenOptional({ user: xxx, store: TypeORMStore, cookie: true }).

4. Open config/default.json (or config/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"	
       }
     },
     ...
   }

5. Open config/production.json (or config/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"	
         }
       }	
     }	
   }
   

6. 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);

7. 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

1. Install the package @foal/csrf.

   npm install @foal/csrf
   

2. If you use sessions, add the hook @CsrfTokenRequired() after @TokenRequired(...)

   Example

   import { CsrfTokenRequired } from '@foal/csrf';
   
   @TokenRequired({
     cookie: true,
     /* ... */
   })
   @CsrfTokenRequired()
   export class ApiController {
     // ...
   }

3. 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 {
   
   }

4. The CSRF configuration has changed from

   settings:
     csrf: true

   to

   settings:
     csrf:
       enabled: true

5. Replace ctx.request.csrfToken() with getCsrfToken(ctx.session) if you use sessions or getCsrfToken() 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
       );
     }
   
   }