v5.2.1

Fixes / features

• Upgrade AJV sub-dependency to address CVE-2025-69873. Thank to @apptio-mrejdych for reporting this.

Dependencies

• @foal/aws-s3
  • @aws-sdk/client-s3@3.990
  • @aws-sdk/lib-storage@3.990
• @foal/cli
  • ajv@8.18
• @foal/core
  • ajv@8.18
• @foal/graphql
  • ajv@8.18

v5.2.0

Features

• Add PasswordService and allow to auto-upgrade outdated password hashes. (PR: #1338)
• Make TypeORM store support strings as user ID (such as UUID) (PR: #1349)

How to migrate

If you use TypeORM store:

npm run makemigrations
npm run migrations

Chore

• [Internal] [CLI] Re-organize CLI directory (PR: #1340)
• [Internal] [CLI] Divide FileSystem into two services (PR: #1343)

v5.1.3

Bug fix

• [CLI] Fix thrown error when running npx foal run with arguments (regression) (issue: #1346) (PR: #1347)

v5.1.2

Patches

This version upgrades the minor version of the express dependency.

Dependencies

• @foal/core
  • express@4.22

v5.1.1

This patch release upgrades the TypeORM version used in the package.json generated by the CLI.

v5.1.0

Features

• Support Node v24 (PR: #1325)
• Allow to create a directory if it does not exist with Disk and LocalDisk (PR: #1334)
• Allow to add a log context only applicable for error-level logs (PR: #1335)
• Increase password interaction count to 600,000 (PR: #1336)

Enhancements

• Better display errors thrown in main() (issue: #1316) (PR: #1317)
• Do not block AsyncService.run on blocking synchronous function (PR: #1328)
• Add OpenAPI documentation to PermissionRequired hook (PR: #1329)

Chores

• Fix testing issues to make the CI pass (PR: #1322, #1332)
• Re-organize repository (PR: #1323)
• Move documentation tests to a separate directory (PR: #1324)
• Upgrade dependencies (PR: #1326)
• Replace glob dependency with new native Node API (PR: #1331)

Dependencies

• @foal/aws-s3
  • @aws-sdk/client-s3@3.926
  • @aws-sdk/lib-storage@3.926
• @foal/cli
  • commander@14.0
• @foal/graphql
  • glob (removed)
• @foal/swagger-ui-dist
  • swagger-ui-dist@5.30

v5.0.1

Fixes

• Make create-userscript generated with createapp work with MongoDB (PR: #1314)

v5.0.0

Supported versions of Node and TypeScript

• Support for Node 18 and Node 20 has been dropped and support for Node 22 has been added. Foal code is now compiled to ES2023.

• The minimum supported version of TypeScript is version 5.5. Update your package.json file accordingly.

  npm install typescript@5.5

  If you're using the GraphQLController with the resolvers property, you need to add the declare keyword before the property name:

  export class ApiController extends GraphQLController {
    schema = // ...
  
    @dependency
    declare resolvers: RootResolverService;
  }

TypeORM upgrade

• The minimum required version of TypeORM is v0.3.24.

  npm install typeorm@0.3.24

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.

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

Controller parameters

To facilitate the typing of the request body, path parameters and request parameters in controllers, the request object is now passed as a second argument to controller methods.

    interface MyQuery {
      // ...
    }

    interface MyBody {
      // ...
    }

    interface MyParams {
      // ...
    }

    // Version 4
    class MyController {
      @Get('/foobar')
      foobar(ctx: Context) {
        const query = ctx.request.query as MyQuery;
        const body = ctx.request.body as MyQuery;
        const params = ctx.request.params as MyParams;

        // Do something
      }
      // OR
      @Get('/foobar')
      foobar(ctx: Context, params: MyParams, body: MyBody) {
        const query = ctx.request.query as MyQuery;

        // Do something
      }
    }

    // Version 5
    class MyController {
      @Get('/foobar')
      foobar(ctx: Context, { query, body, params }: { query: MyQuery, body: MyBody, params: MyParams }) {
        // Do something
      }
    }

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.

  // Version 4
  this.logger.addLogContext('foo', 'bar');
  this.logger.addLogContext('barfoo', 'foobar');
  
  // Version 5
  this.logger.addLogContext({
    foo: 'bar',
    barfoo: 'foobar',
  });

• The deprecated settings.loggerFormat configuration has been removed. If you want to disable HTTP logging, replace configuration settings.loggerFormat: 'none' with settings.logger.logHttpRequests: false.

  // Version 4
  {
    "settings": {
      "loggerFormat": "none"
    }
  }
  
  // Version 5
  {
    "settings": {
      "logger": {
        "logHttpRequests": false
      }
    }
  }
  
  // Version 4
  {
    "settings": {
      "loggerFormat": "any other value than 'none'"
    }
  }
  
  // Version 5
  {
    "settings": {}
  }

Shell scripts

• The main function of shell scripts now receives an instance of ServiceManager as second argument and the logger as third argument:

  // Version 4
  export async function main(args: any) {
    // ...
  }
  
  // Version 5
  export async function main(args: any, services: ServiceManager, logger: Logger) {
    // ...
  }

• Log context are supported.

• When running a script, the script name as well as a script ID are added to the log context.

• At the end of script execution, as with an HTTP request, a log is printed to indicate whether the execution was successful or unsuccessful.

• Any error thrown in the main function is now logged with the framework logger.

  // Version 4
  export async function main() {
    const services = new ServiceManager();
    const logger = services.get(Logger);
  
    try {
      // ...
      throw new Error('Hello world');
    } catch(error) {
      logger.error(error.message { error });
    }
  }
  
  // Version 5
  export async function main() {
    // ...
    throw new Error('Hello world');
  }

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.

  // Version 4
  return this.googleProvider.redirect();
  
  // Version 5
  return this.googleProvider.createHttpResponseWithConsentPageUrl({ isRedirection: true });

Dependencies

• @foal/cli
  • node-fetch removed
• @foal/graphql
  • glob@11
• @foal/social
  • node-fetch removed
• @foal/typeorm
  • typeorm@0.3.24 (peer dependency)
• @foal/aws-s3
  • @aws-sdk/client-s3@3.817
  • @aws-sdk/lib-storage@3.817
• @foal/jwks-rsa
  • `jwks-rsa@3.2
• @foal/socket.io
  • socket.io@4.8
• @foal/swagger
  • `swagger-ui-dist@5.22

PR

#1280

v4.6.0

Features

• Remove deprecated security header X-XSS-Protection (issue: #1305, PR: #1311)

v4.5.1

Features

Some security vulnerabilities were showing up with npm audit. This version updates Foal's dependencies to get rid of them.

Dependencies

• @foal/acceptance-tests
  • express@4.21
  • redis@4.7
• @foal/aws-s3
  • @aws-sdk/client-s3@3.651
  • @aws-sdk/lib-storage@3.651
• @foal/core
  • express@4.21
• @foal/examples
  • concurrently@9.0
• @foal/redis
  • redis@4.7