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 to hashPassword.
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/
  ...
...
```
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"
  ...
...
```

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, the createApp 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 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');

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.

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

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 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.
If you do not use Server-Side Rendering with EJS, you can uninstall the @foal/ejs package from your application.
```
npm uninstall @f...
```

Features

Update to v0.8 the message displayed with 500 errors (issue: #387).
Have a CLI command to generate secrets (issue: #365) (PR: #392).
[@foal/cli] New projects will use source maps when displaying error traceback upon unit and e2e testing (issue: #385) (PR: #391).
Support stateless CSRF protection using double submit cookie technique (issue: #363) (PR: #396).
Be able to specify a virtual path prefix for static files (issue: #382) (PR: #393).
Provide a class ConfigMock to mock the Config when it used as a service (issue: #367) (PR: #394).
Add a ValidateCookies hook (issue: #375) (PR: #398).
Support file uploads and downloads (issues: #374, #298)

How to upgrade

npm install -g @foal/cli
npm update # in your project

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Features

Contributors

Content

What's new?

Features (formal)

How to Upgrade to Version 1

Mandatory

Recommended

Optional

Features

How to upgrade

Features

How to upgrade

Features

How to upgrade

Contributors

Features

How to upgrade

Features

Releases: FoalTS/foal

v1.2.0

v1.1.1

v1.1.0

Features

Contributors

Fix small inconsistencies and bugs in v1.0.0

Content

Version 1.0.0

What's new?

Features (formal)

How to Upgrade to Version 1

Mandatory

Recommended

Optional

May Release

Features

How to upgrade

April Release

Features

How to upgrade

March Release

Features

How to upgrade

Contributors

v0.8.6

Features

How to upgrade

v0.8.5

Features