v5.0.0

.github/CONTRIBUTING.MD

@@ -136,7 +136,8 @@ All of major releases are supported for at least 18 months.
 
 | Release | Status | Active Start | Maintenance Start | End-of-life | Node versions | TS min version |
 | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
-| 4.x | *Active* | 2023-09-06 | | | 18, 20 | 4.9 |
+| 5.x | *Active* | TODO | | | 20, 22 | 5.5 |
+| 4.x | *Maintenance* | 2023-09-06 | TODO | TODO | 18, 20 | 4.9 |
 | 3.x | *End-of-Life* | 2022-10-28 | 2023-09-06 | 2024-03-06 | 16, 18 | 4.7 |
 | 2.x | *End-of-Life* | 2020-12-03 | 2022-10-28 | 2023-04-30 | 10, 12, 14 | 4.0 |
 | 1.x | *End-of-Life* | 2019-07-11 | 2020-12-03 | 2021-05-31 | 8, 10 | 3.5 |

.github/workflows/daily-test.yml

@@ -11,7 +11,7 @@ jobs:
  strategy:
  matrix:
  os: [ubuntu-latest]
- node-version: [18, 20]
+ node-version: [20, 22]
 
  services:
  mongodb:

.github/workflows/documentation.yml

@@ -14,7 +14,7 @@ jobs:
  - uses: actions/checkout@v1
  - uses: actions/setup-node@v1
  with:
- node-version: '18.x'
+ node-version: '20.x'
  - name: Test Build
  run: |
  cd docs
@@ -33,7 +33,7 @@ jobs:
  - uses: actions/checkout@v1
  - uses: actions/setup-node@v1
  with:
- node-version: '18.x'
+ node-version: '20.x'
  - name: Add key to allow access to repository
  env:
  SSH_AUTH_SOCK: /tmp/ssh_agent.sock

.github/workflows/test.yml

@@ -13,7 +13,7 @@ jobs:
 
  strategy:
  matrix:
- node-version: [18, 20]
+ node-version: [20, 22]
 
  env:
  SETTINGS_AWS_ACCESS_KEY_ID: ${{ secrets.SETTINGS_AWS_ACCESS_KEY_ID }}
@@ -29,8 +29,6 @@ jobs:
  uses: actions/setup-node@v1
  with:
  node-version: ${{ matrix.node-version }}
- - name: Use npm version 9.6
- run: npm install -g npm@9.6
  - name: Install project and package dependencies
  run: npm install
  - name: Build packages

docs/blog/version-5.0-release-notes.md

@@ -0,0 +1,88 @@
+---
+title: Version 5.0 release notes
+authors: LoicPoullain
+image: blog/twitter-banners/version-5.0-release-notes.png
+tags: [release]
+---
+
+![Banner](./assets/version-5.0-is-here/banner.png)
+
+Version 5.0 of [Foal](https://foalts.org/) is out!
+
+<!--truncate-->
+
+## Supported versions of Node and TypeScript
+
+- Support for Node 18 has been dropped and support for Node 22 has been added. Foal code is now compiled to ES2023.
+- The supported version of TypeScript is version 5. Update your `package.json` file accordingly.
+
+> If you're using the `GraphQLController` with the `resolvers` property, you need to add the `declare` keyword before the property name:
+> ```typescript
+> 
+> export class ApiController extends GraphQLController {
+> schema = // ...
+>
+> @dependency
+> declare resolvers: RootResolverService;
+> }
+> ```
+
+## TypeORM upgrade
+
+- The minimum required version of TypeORM is v0.3.20.
+
+## Better typing
+
+- The default type of `Context.state` is now `{}`. This way, you'll get a compilation error if you forget to specify a type for the state.
+
+ ```typescript
+ // Version 4
+ class MyController {
+ @Get('/foobar')
+ foobar(ctx: Context) {
+ // Does not throw.
+ console.log(ctx.state.shoppingCart);
+ }
+ }
+
+ // Version 5
+ class MyController {
+ @Get('/foobar')
+ foobar(ctx: Context) {
+ // Throws a compilation error: Property 'shoppingCart' does not exist on type '{}'.ts(2339)
+ console.log(ctx.state.shoppingCart);
+ }
+ }
+
+ // Version 5 (without error)
+ class MyController {
+ @Get('/foobar')
+ foobar(ctx: Context<any, { shoppingCart: object }>) {
+ console.log(ctx.state.shoppingCart);
+ }
+ }
+
+ ```
+
+- The return value of the social services `getUserInfoFromTokens` method is now typed.
+
+## Logging
+
+- The `Logger.addLogContext(key, value)` method now accepts a record as parameter: `Logger.addLogContext(context)`. This makes the function's signature more consistent with other logging methods (`info`, `warn`, etc.) and allows multiple keys/values to be passed at once.
+- The deprecated `settings.loggerFormat` configuration has been removed. If you want to disable HTTP logging, set `settings.logger.logHttpRequests` to false instead.
+
+## Shell scripts
+
+- The `main` function of shell scripts now receives an instance of `ServiceManager` as second argument:
+ ```typescript
+ export async function main(args: any, services: ServiceManager) {
+ // ...
+ }
+ ```
+
+
+## Removal of deprecated components
+
+- The deprecated hook `@Log` has been removed. Use the `Logger` service in a custom `@Hook` instead.
+- The command alias `npx foal run-script` has been removed. Use `npx foal run` instead.
+- The deprecated method `AbstractProvider.redirect` has been removed. Use `AbstractProvider.createHttpResponseWithConsentPageUrl({ isRedirection: true })` instead.

docs/docs/architecture/architecture-overview.md

@@ -76,7 +76,7 @@ Controllers may have sub-controllers. Hooks can be attached to the controllers o
 Here's an example of what a FoalTS application may look like.
 
 ```typescript
-import { Context, controller, Get, HttpResponseNotFound, HttpResponseOK, Log } from '@foal/core';
+import { Context, controller, Get, Hook, HttpResponseNotFound, HttpResponseOK } from '@foal/core';
 import { JWTRequired } from '@foal/jwt';
 
 @JWTRequired()
@@ -105,7 +105,9 @@ class ApiController {
  }
 }
 
-@Log('Receiving a request...')
+@Hook(() => {
+ console.log('Receiving a request...')
+})
 class AppController {
  subControllers = [
  controller('/api', ApiController)

docs/docs/architecture/controllers.md

@@ -100,7 +100,7 @@ It has seven properties:
 | Name | Type | Description |
 | --- | --- | --- |
 | `request` | `Request` | Gives information about the HTTP request. |
-| `state` | `{ [key: string]: any }` | Object which can be used to forward data accross several hooks (see [Hooks](./hooks.md)). |
+| `state` | `{ [key: string]: any } = {}` | Object which can be used to forward data accross several hooks (see [Hooks](./hooks.md)). |
 | `user` | `{ [key: string]: any }`\|`null` | The current user (see [Authentication](../authentication/quick-start.md)). | 
 | `session`| `Session`\|`null` | The session object if you use sessions. |
 | `files` | `FileList` | A list of file paths or buffers if you uploaded files (see [Upload and download files](../common/file-storage/upload-and-download-files.md)). |

docs/docs/architecture/hooks.md

@@ -23,7 +23,6 @@ They improve code readability and make unit testing easier.
 Foal provides a number of hooks to handle the most common scenarios.
 
 - `ValidateBody`, `ValidateHeader`, `ValidatePathParam`, `ValidateCookie` and `ValidateQueryParam` validate the format of the incoming HTTP requests (see [Validation](../common/validation-and-sanitization.md)).
-- `Log` displays information on the request (see [Logging](../common/logging.md)).
 - `JWTRequired`, `JWTOptional`, `UseSessions` authenticate the user by filling the `ctx.user` property.
 - `PermissionRequired` restricts the route access to certain users.
 
@@ -73,7 +72,7 @@ If the user makes a POST request to `/products` whereas she/he is not authentica
 > If you need to apply a hook globally, you just have to make it decorate the root controller: `AppController`.
 >
 > ```typescript
-> @Log('Request body:', { body: true })
+> @UseSessions()
 > export class AppController {
 > // ...
 > }
@@ -466,7 +465,7 @@ import { Context, Get, Hook, HttpResponseOK, UserRequired } from '@foal/core';
 import { Org } from '../entities';
 
 function AddOrgToContext() {
- return Hook(async ctx => {
+ return Hook(async (ctx: Context<any, { org: Org }>) => {
  if (ctx.user) {
  ctx.state.org = await Org.findOneByOrFail({ id: ctx.user.orgId });
  }
@@ -478,7 +477,7 @@ export class ApiController {
  @Get('/org-name')
  @UserRequired()
  @AddOrgToContext()
- readOrgName(ctx: Context) {
+ readOrgName(ctx: Context<any, { org: Org }>) {
  return new HttpResponseOK(ctx.state.org.name);
  }
 

docs/docs/authentication/session-tokens.md

@@ -71,7 +71,7 @@ module.exports = {
 #### TypeORMStore
 
 ```
-npm install typeorm@0.3.17 @foal/typeorm
+npm install typeorm@0.3.20 @foal/typeorm
 ```
 
 This store uses the default TypeORM connection whose configuration is usually specified in `config/default.{json|yml|js}`.
@@ -641,7 +641,7 @@ npx foal g script revoke-session
 Open `scripts/revoke-session.ts` and update its content.
 
 ```typescript
-import { createService, readSession, Store } from '@foal/core';
+import { readSession, ServiceManager, Store } from '@foal/core';
 
 import { dataSource } from '../db';
 
@@ -653,10 +653,10 @@ export const schema = {
  required: [ 'token' ]
 }
 
-export async function main({ token }: { token: string }) {
+export async function main({ token }: { token: string }, services: ServiceManager) {
  await dataSource.initialize();
 
- const store = createService(Store);
+ const store = services.get(Store);
  await store.boot();
 
  const session = await readSession(store, token);
@@ -687,14 +687,14 @@ npx foal g script revoke-all-sessions
 Open `scripts/revoke-all-sessions.ts` and update its content.
 
 ```typescript
-import { createService, Store } from '@foal/core';
+import { ServiceManager, Store } from '@foal/core';
 
 import { dataSource } from '../db';
 
-export async function main() {
+export async function main(args: any, services: ServiceManager) {
  await dataSource.initialize();
 
- const store = createService(Store);
+ const store = services.get(Store);
  await store.boot();
  await store.clear();
 }

docs/docs/authentication/social-auth.md

@@ -343,7 +343,11 @@ export interface GithubUserInfoParameter {
  // ...
 }
 
-export class GithubProvider extends AbstractProvider<GithubAuthParameter, GithubUserInfoParameter> {
+export interface GithubUserInfo {
+ // ...
+}
+
+export class GithubProvider extends AbstractProvider<GithubAuthParameter, GithubUserInfoParameter, GithubUserInfo> {
 
  protected configPaths = {
  clientId: 'social.github.clientId',
@@ -357,7 +361,7 @@ export class GithubProvider extends AbstractProvider<GithubAuthParameter, Github
 
  protected defaultScopes: string[] = [ 'email' ]; // Optional
 
- async getUserInfoFromTokens(tokens: SocialTokens, params?: GithubUserInfoParameter) {
+ getUserInfoFromTokens(tokens: SocialTokens, params?: GithubUserInfoParameter): GithubUserInfo | Promise<GithubUserInfo> {
  // ...
 
  // In case the server returns an error when requesting 

docs/docs/cli/shell-scripts.md

@@ -17,19 +17,19 @@ Remove the content of `src/scripts/display-users.ts` and replace it with the cod
 
 ```typescript
 // 3p
-import { createService } from '@foal/core';
+import { ServiceManager } from '@foal/core';
 
 // App
 import { dataSource } from '../db';
 import { User } from '../app/entities';
 import { Logger } from '../app/services';
 
-export async function main() {
+export async function main(args: any, services: ServiceManager) {
  await dataSource.initialize();
 
  try {
  const users = await User.find();
- const logger = createService(Logger);
+ const logger = services.get(Logger);
  logger.log(users);
  } finally {
  dataSource.destroy();
@@ -55,7 +55,7 @@ npm run build
 Then you can execute it with this command:
 
 ```shell
-npx foal run my-script # or npx foal run-script my-script
+npx foal run my-script
 ```
 
 > You can also provide additionnal arguments to your script (for example: `npx foal run my-script foo=1 bar='[ 3, 4 ]'`). The default template in the generated scripts shows you how to handle such behavior.

docs/docs/common/graphql.md

@@ -194,7 +194,7 @@ export class ApiController extends GraphQLController {
  schema = // ...
 
  @dependency
- resolvers: RootResolverService;
+ declare resolvers: RootResolverService;
 }
 ```