DEV Community: Loïc Poullain

Foal version 5.2 is here 🎉

Loïc Poullain — Thu, 29 Jan 2026 13:20:31 +0000

Version of Foal is there!

PasswordService and automatic password upgrade

Version 5.2 introduces a new PasswordService that centralizes password hashing and verification functionality. This service provides a cleaner API and enables automatic password security upgrades.

New PasswordService

The PasswordService class groups all password-related operations:

import { PasswordService, dependency } from '@foal/core';

export class AuthService {
  @dependency
  passwordService: PasswordService;

  async createUser(email: string, password: string) {
    const passwordHash = await this.passwordService.hashPassword(password);
    // Save user with passwordHash
  }

  async verifyUserPassword(plainPassword: string, passwordHash: string): Promise<boolean> {
    return this.passwordService.verifyPassword(plainPassword, passwordHash);
  }
}

Automatic password upgrade

One of the key features of the new service is the ability to automatically upgrade password hashes when they become outdated. This is particularly useful when security standards evolve (e.g., when the number of PBKDF2 iterations increases).

The verifyPassword method now accepts an optional onPasswordUpgrade callback that is called when a password hash needs to be upgraded:

import { PasswordService, dependency } from '@foal/core';

export class AuthService {
  @dependency
  passwordService: PasswordService;

  @dependency
  userRepository: UserRepository;

  async login(email: string, password: string) {
    const user = await this.userRepository.findByEmail(email);

    const isValid = await this.passwordService.verifyPassword(
      password,
      user.passwordHash,
      {
        onPasswordUpgrade: async (newHash) => {
          // Automatically save the upgraded hash
          await this.userRepository.updatePasswordHash(user.id, newHash);
        }
      }
    );

    if (!isValid) {
      throw new Error('Invalid credentials');
    }

    // User is authenticated
  }
}

When a user logs in with a password that was hashed with an older security standard, the service automatically:

Verifies the password is correct
Detects that the hash needs to be upgraded
Generates a new hash with the current security standards
Calls the onPasswordUpgrade callback with the new hash
Returns the verification result

This ensures that all password hashes in your database are gradually upgraded to the latest security standards.

Deprecated functions

The standalone functions hashPassword, verifyPassword, and passwordHashNeedsToBeRefreshed are now deprecated in favor of the PasswordService methods.

// Deprecated
import { hashPassword, verifyPassword } from '@foal/core';

// Recommended
import { PasswordService } from '@foal/core';

TypeORMStore now supports string user IDs

The TypeORMStore session store now supports both number and string user IDs. This is particularly useful when using UUIDs or other string-based identifiers as primary keys for your users.

How it works

The sessions table now has two columns for storing user IDs:

user_id (integer, nullable) - for numeric user IDs
user_id_str (varchar(64), nullable) - for string user IDs (UUIDs, etc.)

When saving a session, the store automatically determines which column to use based on the type of the user ID.

Migration

Run the command npm run makemigrations. It will generate a migration to add the new "user_id_str" column in your codebase.

Then run npm run migrations to apply it.

Existing sessions with numeric user IDs will continue to work without any changes.

Article originally published here.

FoalTS - NodeJS framework - version 5.1 is out

Loïc Poullain — Tue, 18 Nov 2025 17:46:08 +0000

Version 5.1 of Foal is out and brings some new features!

Features

The framework is now tested against Node.js 24 and so this version is officially supported.
The Disk and LocalDisk services have a new method mkdirIfNotExists to creates directories. This is useful when using the local file system to ensure that a directory exists before saving files. Otherwise, an error can be thrown when it does not. On cloud storage services such as S3, directories are created automatically when saving files so this method does nothing.
The Logger service has a new method addErrorContext which works like addLogContext but only for error-level logs. This is useful to add context information that is only relevant for errors (e.g. request body, etc.) without polluting the other log levels.
The iteration count of the hashPassword function has been increased to 600,000 to match the latest OWASP recommendations.

Enhancements

On new projects, the generated src/index.ts file has been improved to better log any errors thrown in the main function.
The run function of the AsyncService has been improved to execute functions fully asynchronously, which was not the case before in very specific scenarios.
The missing OpenAPI documentation on the @PermissionRequired hook has been added.

This post was originally posted on FoalTS blog

Node.JS - Foal framework version 4.5 is released 🎉

Loïc Poullain — Sat, 24 Aug 2024 17:47:17 +0000

Version 4.5 of Foal, a full-featured Node.JS framework for building web applications, is out!

Here's what's inside.

Asynchronous tasks

In some situations, we need to execute a specific task without waiting for it and without blocking the request.

This could be, for example, sending a specific message to the CRM or company chat. In this case, the user needs to be able to see his or her request completed as quickly as possible, even if the request to the CRM takes some time or fails.

To this end, Foal version 4.5 provides an AsyncService to execute these tasks asynchronously, and correctly catch and log their errors where appropriate.

import { AsyncService, dependency } from '@foal/core';

import { CRMService } from './somewhere';

export class SubscriptionService {
  @dependency
  asyncService: AsyncService;

  @dependency
  crmService: CRMService;

  async subscribe(userId: number): Promise<void> {
    // Do something

    this.asyncService.run(() => this.crmService.updateUser(userId));
  }
}

Social authentication for SPAs

If you wish to manually manage the redirection to the consent page on the client side (which is often necessary when developing an SPA), you can now do so with the createHttpResponseWithConsentPageUrl method. It returns an HttpResponseOK whose body contains the URL of the consent page.

export class AuthController {
  @dependency
  google: GoogleProvider;

  @Get('/signin/google')
  getConsentPageURL() {
    return this.google.createHttpResponseWithConsentPageUrl();
  }

  // ...

}

Google social authentification

The typing of the GoogleProvider service has been improved. The userInfo property returned by getUserInfo is now typed with the values returned by the Google server.

const { userInfo } = await this.googleProvider.getUserInfo(...);

// userInfo.email, userInfo.family_name, etc

Logging improvements

In previous versions, the util function displayServerURL and configuration errors printed logs on several lines, which was not appropriate for logging software.

From version 4.5 onwards, configuration errors are displayed on a single line and the displayServerURL function is marked as deprecated.

CLI fixes

When running npx foal connect react to connect the React application to the Foal application in development, the following features did not work:

Proxify requests from the client to the server without needing to enable CORS or specify a different port in development.
Build the client application in the server application's public directory.

This is fixed in v4.5.

Global use of CLI deprecated

In previous versions, the tutorial suggested installing the CLI globally to create a new application or generate files. However, it is considered bad practice to install a dependency globally for local use.

In addition, the CLI was also installed locally so that the build command would work when deploying the application to a CI or to production. This was maintaining two versions of the CLI.

To correct this, in the documentation and examples, the CLI is now always installed and used locally. To use it, simply add npx before each command (except for createapp).

# Before
foal createapp my-app

foal generate script foobar
foal createsecret

# After
npx @foal/cli createapp my-app

npx foal generate script foobar
npx foal createsecret

This post was originally published on Foal's blog.

Node.JS - Version 4.3 of Foal framework has been released

Loïc Poullain — Thu, 18 Apr 2024 07:54:33 +0000

Version 4.3 of Foal is out!

As a reminder, Foal is a full-featured Node.JS framework for building web applications.

Better CLI ouput when script arguments are invalid

Previously, when executing foal run my-script with invalid arguments, the CLI would only display one error at a time.

For example, with the following schema and arguments, we would only get this error message:

export const schema = {
  type: 'object', 
  properties: {
    email: { type: 'string', format: 'email', maxLength: 2 },
    password: { type: 'string' },
    n: { type: 'number', maximum: 10 }
  },
  required: ['password']
};

foal run my-script email=bar n=11

Error: The command line arguments must match format "email".

From version 4.3 onwards, the CLI logs all validation errors and with a more meaningful description.

Script error: arguments must have required property 'password'.
Script error: the value of "email" must NOT have more than 2 characters.
Script error: the value of "email" must match format "email".
Script error: the value of "n" must be <= 10.

[Fix] the logger no longer throws an error in development when the client request is interrupted

Using the logger's dev format, Foal would occasionally throw the error TypeError: Cannot read properties of null.

This would occur when the connection with the client was lost, which happens, for example, when the React client server hotly reloads.

This version fixes this error.

This post was originally published on FoalTS blog

Foal version 3.0 is here 🚀

Loïc Poullain — Wed, 02 Nov 2022 06:11:23 +0000

Version 3.0 of Foal is finally there!

It's been a long work and I'm excited to share with you the new features of the framework 🎉 . The upgrading guide can be found here.

Here are the new features and improvements of version 3!

For those who don't know it yet, Foal is a 5-year-old full-featured Node.JS framework for building web applications. It is simple and easy to use, based on TypeScript with very detailed documentation. And the best part: it is tested by more than 2,000 tests.

Full support of TypeORM v0.3

TypeORM v0.3 provides greater typing safety and this is something that will be appreciated when moving to the new version of Foal.

The version 0.3 of TypeORM has a lot of changes compared to the version 0.2 though. Features such as the ormconfig.json file have been removed and functions such as createConnection, getManager or getRepository have been deprecated.

A lot of work has been done to make sure that @foal/typeorm, new projects generated by the CLI and examples in the documentation use version 0.3 of TypeORM without relying on deprecated functions or patterns.

In particular, the connection to the database is now managed by a file src/db.ts that replaces the older ormconfig.json.

For those new to Foal, TypeORM is the default ORM used in all new projects. But you can use any other ORM or query builder if you want, as the core framework is ORM independent.

Code simplified

Some parts of the framework have been simplified to require less code and make it more understandable.

Authentication

The @UseSessions and @JWTRequired authentication hooks called obscure functions such as fetchUser, fetchUserWithPermissions to populate the ctx.user property. The real role of these functions was not clear and a newcomer to the framework could wonder what they were for.

This is why these functions have been removed and replaced by direct calls to database models.

// Version 2
@UseSessions({ user: fetchUser(User) })
@JWTRequired({ user: fetchUserWithPermissions(User) })

// Version 3
@UseSessions({ user: (id: number) => User.findOneBy({ id }) })
@JWTRequired({ user: (id: number) => User.findOneWithPermissionsBy({ id }) })

File upload

When uploading files in a multipart/form-data request, it was not allowed to pass optional fields. This is now possible.

The interface of the @ValidateMultipartFormDataBody hook, renamed to @ParseAndValidateFiles to be more understandable for people who don't know the HTTP protocol handling the upload, has been simplified.

Examples with only files

// Version 2
@ValidateMultipartFormDataBody({
  files: {
    profile: { required: true }
  }
})

// Version 3
@ParseAndValidateFiles({
  profile: { required: true }
})

Examples with files and fields

// Version 2
@ValidateMultipartFormDataBody({
  files: {
    profile: { required: true }
  }
  fields: {
    description: { type: 'string' }
  }
})

// Version 3
@ParseAndValidateFiles(
  {
    profile: { required: true }
  },
  // The second parameter is optional
  // and is used to add fields. It expects an AJV object.
  {
    type: 'object',
    properties: {
      description: { type: 'string' }
    },
    required: ['description'],
    additionalProperties: false
  }
)

Database models

Using functions like getRepository or getManager to manipulate data in a database is not necessarily obvious to newcomers. It adds complexity that is not necessary for small or medium sized projects. Most frameworks prefer to use the Active Record pattern for simplicity.

This is why, from version 3 and to take into account that TypeORM v0.3 no longer uses a global connection, the examples in the documentation and the generators will extend all the models from BaseEntity. Of course, it will still be possible to use the functions below if desired.

// Version 2
@Entity()
class User {}

const user = getRepository(User).create();
await getRepository(User).save(user);

// Version 3
@Entity()
class User extends BaseEntity {}

const user = new User();
await user.save();

Better typing

The use of TypeScript types has been improved and some parts of the framework ensure better type safety.

Validation with AJV

Foal's version uses ajv@8 which allows you to bind a TypeScript type with a JSON schema object. To do this, you can import the generic type JSONSchemaType to build the interface of the schema object.

import { JSONSchemaType } from 'ajv';

interface MyData {
  foo: number;
  bar?: string
}

const schema: JSONSchemaType<MyData> = {
  type: 'object',
  properties: {
    foo: { type: 'integer' },
    bar: { type: 'string', nullable: true }
  },
  required: ['foo'],
  additionalProperties: false
}

File upload

In version 2, handling file uploads in the controller was tedious because all types were any. Starting with version 3, it is no longer necessary to cast the types to File or File[]:

// Version 2
const name = ctx.request.body.fields.name;
const file = ctx.request.body.files.avatar as File;
const files = ctx.request.body.files.images as File[];

// After
const name = ctx.request.body.name;
// file is of type "File"
const file = ctx.files.get('avatar')[0];
// files is of type "Files"
const files = ctx.files.get('images');

Authentication

In version 2, the user option of @UseSessions and @JWTRequired expected a function with this signature:

(id: string|number, services: ServiceManager) => Promise<any>;

There was no way to guess and guarantee the type of the user ID and the function had to check and convert the type itself if necessary.

The returned type was also very permissive (type any) preventing us from detecting silly errors such as confusion between null and undefined values.

In version 3, the hooks have been added a new userIdType option to check and convert the JavaScript type if necessary and force the TypeScript type of the function. The returned type is also safer and corresponds to the type of ctx.user which is no longer any but { [key : string] : any } | null.

Example where the ID is a string

@JWTRequired({
  user: (id: string) => User.findOneBy({ id });
  userIdType: 'string',
})

Example where the ID is a number

@JWTRequired({
  user: (id: number) => User.findOneBy({ id });
  userIdType: 'number',
})

By default, the value of userIdType is a number, so we can simply write this:

@JWTRequired({
  user: (id: number) => User.findOneBy({ id });
})

GraphQL

In version 2, GraphQL schemas were of type any. In version 3, they are all based on the GraphQLSchema interface.

Closer to JS ecosystem standards

Some parts have been modified to get closer to the JS ecosystem standards. In particular:

Development command

The npm run develop has been renamed to npm run dev.

Configuration through environment variables

When two values of the same variable are provided by a .env file and an environment variable, then the value of the environment is used (the behavior is similar to that of the dotenv library).

`null` vs `undefined` values

When the request has no session or the user is not authenticated, the values of ctx.session and ctx.user are null and no longer undefined. This makes sense from a semantic point of view, and it also simplifies the user assignment from the find functions of popular ORMs (Prisma, TypeORM, Mikro-ORM). They all return null when no value is found.

More open to other ORMs

TypeORM is the default ORM used in the documentation examples and in the projects generated by the CLI. But it is quite possible to use another ORM or query generator with Foal. For example, the authentication system (with sessions or JWT) makes no assumptions about database access.

Some parts of the framework were still a bit tied to TypeORM in version 2. Version 3 fixed this.

Shell scripts

When running the foal generate script command, the generated script file no longer contains TypeORM code.

Permission system

The @PermissionRequired option is no longer bound to TypeORM and can be used with any ctx.user that implements the IUserWithPermissions interface.

Smaller AWS S3 package

The @foal/aws-s3 package is now based on version 3 of the AWS SDK. Thanks to this, the size of the node_modules has been reduced by three.

Dependencies updated and support of Node latest versions

All Foal's dependencies have been upgraded. The framework is also tested on Node versions 16 and 18.

Some bug fixes

If the configuration file production.js explicitly returns undefined for a given key and the default.json file returns a defined value for this key, then the value from the default.json file is returned by Config.get.

Article originally published here.

Foal v2.11 has been released with better password management

Loïc Poullain — Mon, 10 Oct 2022 06:24:27 +0000

Version 2.11 of Foal is out! Here are the improvements that it brings:

Number of Iterations on Password Hashing Has Been Increased

The PBKDF2 algorithm (used for password hashing) uses a number of iterations to hash passwords. This work factor is deliberate and slows down potential attackers, making attacks against hashed passwords more difficult.

As computing power increases, the number of iterations must also increase. This is why, starting with version 2.11, the number of iterations has been increased to 310,000.

To check that an existing password hash is using the latest recommended number of iterations, you can use the passwordHashNeedsToBeRefreshed function.

The example below shows how to perform this check during a login and how to upgrade the password hash if the number of iterations turns out to be too low.

const { email, password } = ctx.request.body;

const user = await User.findOne({ email });

if (!user) {
  return new HttpResponseUnauthorized();
}

if (!await verifyPassword(password, user.password)) {
  return new HttpResponseUnauthorized();
}

// highlight-start
// This line must be after the password verification.
if (passwordHashNeedsToBeRefreshed(user.password)) {
  user.password = await hashPassword(password);
  await user.save();
}
// highlight-end

// Log the user in.

How to use VSCode debugger with multiple Docker services

Loïc Poullain — Mon, 29 Aug 2022 15:17:41 +0000

In my company, we use Docker and Docker Compose to run our Node.js services locally. Recently, I needed to configure and run the VSCode debugger on some of these services to debug a feature. There are a few things to know to achieve this, which I will share in this article with some basic examples.

Before we start, here are the points that will serve as a guideline in this tutorial:

We want to keep using Docker and Docker compose to run our services, so that we have the proper environment for each of these services (environment variables, etc).
We do not want to touch the current docker-compose.yml which could, potentially, be used in the future to deploy our services in production.

The Sample Application

Let's start by creating a first service. It is a simple web server that concatenates two strings, a first name and a last name, and returns the result. This service will live in a webapp/ directory at the root of the project.

The Node.JS code

webapp/package.json

{
    "name": "webapp",
    "scripts": {
        "start": "node src/server.js"
    },
    "dependencies": {
        "express": "^4.16.1"
    }
}

webapp/src/server.js

const express = require('express');
const app = express();

app.get('/fullname', (req, res) => {
    const firstName = req.query.firstNme;
    const lastName = req.query.lastName;
    res.send(`${firstName} ${lastName}`);
});

app.listen(8080, () => console.log('Listening on port 8080...'));

webapp/Dockerfile

FROM node:16

WORKDIR /usr/src/app

COPY package*.json ./

RUN npm install
COPY . .

EXPOSE 8080
CMD [ "node", "src/server.js" ]

webapp/.dockerignore

node_modules
npm-debug.log

The Docker configuration

Now that the application code is written and the Dockerfile created, we can add a docker-compose.yml file at the root of the project.

docker-compose.yml

services:
    webapp:
        build: ./webapp
        ports:
            - "127.0.0.1:8080:8080"

Let's start the service.

docker-compose build
docker-compose up -d

If you go to http://localhost:8080/fullname?firstName=Foo&lastName=Bar, you should see the string undefined Bar, which is the unexpected behavior we will debug.

Debugging the Application in Docker with VSCode

The debugger command

To allow the future VSCode debugger to attach to the Node service, we need to specify it when we start the process by adding the --inpect flag.

Simply using --inspect or --inspect=127.0.0.1:9229 is not sufficient here because we need the 9229 port to be accessible from outside the service, which is allowed by the 0.0.0.0 address. So this command should only be used when you run the debugger in a Docker service. Otherwise, you would expose the port and the debugger to anyone on the Internet.

webapp/package.json

{
    "name": "webapp",
    "scripts": {
        "start": "node src/server.js",
        "start:docker:debug": "node --inspect=0.0.0.0:9229 src/server.js"
    },
    "dependencies": {
        "express": "^4.16.1"
    }
}

The Docker configuration

Following our guideline, we do not modify the initial docker-compose.yml but create a second one that extends the first one. We will use the -f flag of the docker-compose CLI to use them both.

docker-compose.debug.yml

services:
    webapp:
        command: [ 'npm', 'run', 'start:docker:debug' ]
        ports:
            - "127.0.0.1:8080:8080"
            - "127.0.0.1:9229:9229"

Then, to restart the service with debug mode enabled, you can use this command:

docker-compose build
docker-compose -f docker-compose.yml -f docker-compose.debug.yml up -d

The service is now ready to be attached to the VSCode debugger.

Running the debugger with VSCode

At the root of your project, create a new directory .vscode and add the following configuration file.

.vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "attach",
            "name": "Debug webapp",
            "remoteRoot": "/app/src",
            "localRoot": "${workspaceFolder}/webapp/src"
        }
    ]
}

When adding a breakpoint, the remoteRoot and localRoot properties will match the file's position in the VSCode environment and its location in the Docker service file system.

You can now start the debugger on the webapp service. Open the debugging panel and select the Debug webapp option. Then click on the play button.

The debugger is started.

Add a breakpoint on line 6 and then go to http://localhost:8080/fullname?firstName=Foo&lastName=Bar.

The debugger stops on line 6 and we can see that the variable firstName is undefined. The problem comes from line 5 where this is a typo on the firstName parameter name.

To close the debugger, click on the button with a red square.

Debugging Multiple Docker Services

The Node.JS micro-service

To take this a step further, we will add another service, named micro-service, which will be called by webapp.

First, copy and paste the contents of the webapp directory into another directory named micro-service.

Then, in the webapp directory, install axios and update the code as follows.

npm install axios

webapp/src/server.js

const express = require('express');
const axios = require('axios');

const app = express();

app.get('/fullname', async (req, res, next) => {
    try {
        const { data: fullName } = await axios.get('http://micro-service:8080/fullname', {
            params: req.query
        });
        res.send(fullName);
    } catch (err) {
        next(err);
    }
});

app.listen(8080, () => console.log('Listening on port 8080...'));

The URL used line 8 is based on the name of the Docker service defined in the next section.

The Docker configuration

Add the new service to your docker-compose.yml. Note that it uses a different port so as not to conflict with the webapp service.

docker-compose.yml

services:
    webapp:
        build: ./webapp
        ports:
            - "127.0.0.1:8080:8080"
    micro-service:
        build: ./micro-service
        ports:
            - "127.0.0.1:3001:8080"

Then, in your docker-compose.debug.yml, add the new service as well. Note that the debugger port is also different from the first one.

docker-compose.debug.yml

services:
    webapp:
        command: [ 'npm', 'run', 'start:docker:debug' ]
        ports:
            - "127.0.0.1:8080:8080"
            - "127.0.0.1:9229:9229"
    micro-service:
        command: [ 'npm', 'run', 'start:docker:debug' ]
        ports:
            - "127.0.0.1:3001:8080"
            - "127.0.0.1:9230:9229"

Now build and start the two services.

docker-compose build
docker-compose -f docker-compose.yml -f docker-compose.debug.yml up -d

Running multiple debuggers with VSCode

The last thing to do is to add the configuration of the second debugger in launch.json.

.vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "attach",
            "name": "Debug webapp",
            "remoteRoot": "/app/src",
            "localRoot": "${workspaceFolder}/webapp/src"
        },
        {
            "type": "node",
            "request": "attach",
            "name": "Debug micro-service",
            "port": 9230,
            "remoteRoot": "/app/src",
            "localRoot": "${workspaceFolder}/micro-service/src"
        }
    ]
}

Once the configuration is added, you can run the two debuggers for each service.

Once both debuggers are started, add a breakpoint in each service and go to http://localhost:8080/fullname?firstName=Foo&lastName=Bar. The application will stop successively on each breakpoint.

Your VSCode debugger is now fully configured to work with your Docker services. Congratulations!

Article originally published here: https://loicpoullain.com/software-engineering/articles/how-to-use-vscode-debugger-with-multiple-docker-services/

Version 2.10 of Foal is out!

Loïc Poullain — Mon, 15 Aug 2022 15:50:43 +0000

Version 2.10 of Foal is out! This small release brings some tiny improvements.

What's Foal?

It is a full-featured Node.js framework simple and easy to use, written in TypeScript and with a complete documentation.

`@foal/cli` package included by default as dev dependency

Issue: #1097

The @foal/cli package is now installed by default as dev dependency. In this way, all commands of package.json still work when deploying the application to a Cloud provider that does not have the CLI installed globally.

Contributor: @scho-to

Preventing the `npm run develop` command to get stuck on some OS

Issues: #1022, #1115

The npm run develop was getting stuck on some OS based on the configuration of the app. This issue is now fixed in new projects. For current applications, you will need to add a -r flag to the package.json commands using concurrently.

Smaller `main` function

The main function that bootstraps the application is now smaller in new projects.

Article originally published here

FoalTS 2022 survey is open!

Loïc Poullain — Mon, 13 Jun 2022 05:31:38 +0000

FoalTS 2022 survey is now open (yes, a few months late 🙃)!

Your responses to these questions are really valuable as they help me better understand what you need and how to improve the framework going forward 👌.

I read every response carefully so feel free to say anything you have to say!

👉 The link to the survey.

The survey closes on June 31.

FoalTS framework - Version 2.9 is here 🎉

Loïc Poullain — Mon, 30 May 2022 06:31:00 +0000

Version 2.9 of Foal has been released! Here are the improvements that it brings.

New OAuth2 Twitter Provider

After LinkedIn, Google, Github and Facebook, Foal now supports Twitter for social authentication.

👉 Link to the documentation

A big thanks to @LeonardoSalvucci for having implemented this feature.

// 3p
import { Context, dependency, Get } from '@foal/core';
import { TwitterProvider } from '@foal/social';

export class AuthController {
  @dependency
  twitter: TwitterProvider;

  @Get('/signin/twitter')
  redirectToTwitter() {
    // Your "Login In with Twitter" button should point to this route.
    // The user will be redirected to Twitter auth page.
    return this.twitter.redirect();
  }

  @Get('/signin/twitter/callback')
  async handleTwitterRedirection(ctx: Context) {
    // Once the user gives their permission to log in with Twitter, the OAuth server
    // will redirect the user to this route. This route must match the redirect URI.
    const { userInfo, tokens } = await this.twitter.getUserInfo(ctx);

    // Do something with the user information AND/OR the access token.
    // If you only need the access token, you can call the "getTokens" method.

    // The method usually ends with a HttpResponseRedirect object as returned value.
  }

}

OAuth2 Providers support PKCE Code Flow

OAuth2 abstract provider now supports PKCE code flow. If you wish to implement your own provider using PKCE, it's now possible!

Support for version 15 of `graphql` and latest version of `type-graphql`

Foal's dependencies have been updated so as to support the latest version of TypeGraphQL.

Original publication: https://foalts.org/blog/2022/05/29/version-2.9-release-notes

FoalTS framework - version 2.8 is here with complete Websocket support 🎉

Loïc Poullain — Tue, 15 Feb 2022 06:34:45 +0000

Version 2.8 of FoalTS is here and it brings support for Websocket with all the architecture that comes with it (controllers and sub-controllers, hooks, success and error responses, message broadcasting, rooms, use from HTTP controllers, DI, error-handling, validation, unit testing, horizontal scalability, auto-reconnection, etc)

In case you don't know...

Foal is Node.JS framework

written in TypeScript
fully-featured (dependency injection, local and Cloud storage, CLI, ORM, Swagger auto-generation, test environments, etc)
and with an architecture which keeps complexity away (no over-engineering)

It is backed by more than 2100 tests and 11000 lines of documentation.

Get Started

Server

npm install @foal/socket.io

services/websocket.service.ts

import { EventName, ValidatePayload, SocketIOController, WebsocketContext, WebsocketResponse } from '@foal/socket.io';

export class WebsocketController extends SocketIOController {

  @EventName('create product')
  @ValidatePayload({
    additionalProperties: false,
    properties: { name: { type: 'string' }},
    required: [ 'name' ],
    type: 'object'
  })
  async createProduct(ctx: WebsocketContext, payload: { name: string }) {
    const product = new Product();
    product.name = payload.name;
    await product.save();

    // Send a message to all clients.
    ctx.socket.broadcast.emit('refresh products');
    return new WebsocketResponse();
  }

}

src/index.ts

// ...

async function main() {
  const serviceManager = new ServiceManager();

  const app = await createApp(AppController, { serviceManager });
  const httpServer = http.createServer(app);

  // Instanciate, init and connect websocket controllers.
  await serviceManager.get(WebsocketController).attachHttpServer(httpServer);

  // ...
}

Client

This example uses JavaScript code as client, but socket.io supports also many other languages (python, java, etc).

npm install socket.io-client@4

import { io } from 'socket.io-client';

const socket = io('ws://localhost:3001');

socket.on('connect', () => {

  socket.emit('create product', { name: 'product 1' }, response => {
    if (response.status === 'error') {
      console.log(response.error);
    }
  });

});

socket.on('connect_error', () => {
  console.log('Impossible to establish the socket.io connection');
});

socket.on('refresh products', () => {
  console.log('refresh products!');
});

When using socket.io with FoalTS, the client function emit can only take one, two or three arguments.

socket.emit('event name');
socket.emit('event name', { /* payload */ });
// The acknowledgement callback must always be passed in third position.
socket.emit('event name', { /* payload */ }, response => { /* do something */ });

Architecture

Controllers and hooks

The WebSocket architecture is very similar to the HTTP architecture. They both have controllers and hooks. While HTTP controllers use paths to handle the various application endpoints, websocket controllers use event names. As with HTTP, event names can be extended with subcontrollers.

user.controller.ts

import { EventName, WebsocketContext } from '@foal/socket.io';

export class UserController {

  @EventName('create')
  createUser(ctx: WebsocketContext) {
    // ...
  }

  @EventName('delete')
  deleteUser(ctx: WebsocketContext) {
    // ...
  }

}

websocket.controller.ts

import { SocketIOController, wsController } from '@foal/socket.io';

import { UserController } from './user.controller.ts';

export class WebsocketController extends SocketIOController {
  subControllers = [
    wsController('users ', UserController)
  ];
}

Note that the event names are simply concatenated. So you have to manage the spaces between the words yourself if there are any.

Contexts

The Context and WebsocketContext classes share common properties such as the state, the user and the session.

However, unlike their HTTP version, instances of WebsocketContext do not have a request property but a socket property which is the object provided by socket.io. They also have two other attributes: the eventName and the payload of the request.

Responses

A controller method returns a response which is either a WebsocketResponse or a WebsocketErrorResponse.

If a WebsocketResponse(data) is returned, the server will return to the client an object of this form:

{
  status: 'ok',
  data: data
}

If it is a WebsocketErrorResponse(error), the returned object will look like this:

{
  status: 'error',
  error: error
}

Note that the data and error parameters are both optional.

Hooks

In the same way, Foal provides hooks for websockets. They work the same as their HTTP version except that some types are different (WebsocketContext, WebsocketResponse|WebsocketErrorResponse).

import { EventName, WebsocketContext, WebsocketErrorResponse, WebsocketHook } from '@foal/socket.io';

export class UserController {

  @EventName('create')
  @WebsocketHook((ctx, services) => {
    if (typeof ctx.payload.name !== 'string') {
      return new WebsocketErrorResponse('Invalid name type');
    }
  })
  createUser(ctx: WebsocketContext) {
    // ...
  }
}

Summary table

HTTP	Websocket
`@Get`, `@Post`, etc	`@EventName`
`controller`	`wsController`
`Context`	`WebsocketContext`
`HttpResponse`(s)	`WebsocketResponse`, `WebsocketErrorResponse`
`Hook`	`WebsocketHook`
`MergeHooks`	`MergeWebsocketHooks`
`getHookFunction`, `getHookFunctions`	`getWebsocketHookFunction`, `getWebsocketHookFunctions`

Send a message

At any time, the server can send one or more messages to the client using its socket object.

Server code

import { EventName, WebsocketContext, WebsocketResponse } from '@foal/socket.io';

export class UserController {

  @EventName('create')
  createUser(ctx: WebsocketContext) {
    ctx.socket.emit('event 1', 'first message');
    ctx.socket.emit('event 1', 'second message');
    return new WebsocketResponse();
  }
}

Client code

socket.on('event 1', payload => {
  console.log('Message: ', payload);
});

Broadcast a message

If a message is to be broadcast to all clients, you can use the broadcast property for this.

Server code

import { EventName, WebsocketContext, WebsocketResponse } from '@foal/socket.io';

export class UserController {

  @EventName('create')
  createUser(ctx: WebsocketContext) {
    ctx.socket.broadcast.emit('event 1', 'first message');
    ctx.socket.broadcast.emit('event 1', 'second message');
    return new WebsocketResponse();
  }
}

Client code

socket.on('event 1', payload => {
  console.log('Message: ', payload);
});

Grouping clients in rooms

Socket.io uses the concept of rooms to gather clients in groups. This can be useful if you need to send a message to a particular subset of clients.

import { EventName, SocketIOController, WebsocketContext, WebsocketResponse } from '@foal/socket.io';

export class WebsocketController extends SocketIOController {

  onConnection(ctx: WebsocketContext) {
    ctx.socket.join('some room');
  }

  @EventName('event 1')
  createUser(ctx: WebsocketContext) {
    ctx.socket.to('some room').emit('event 2');
    return new WebsocketResponse();
  }

}

Accessing the socket.io server

You can access the socket.io server anywhere in your code (including your HTTP controllers) by injecting the WsServer service.

import { dependency, HttpResponseOK, Post } from '@foal/core';
import { WsServer } from '@foal/socket.io';

export class UserController {
  @dependency
  wsServer: WsServer;

  @Post('/users')
  createUser() {
    // ...
    this.wsServer.io.emit('refresh users');

    return new HttpResponseOK();
  }
}

Error-handling

Any error thrown or rejected in a websocket controller, hook or service, if not caught, is converted to a WebsocketResponseError. If the settings.debug configuration parameter is true, then the error is returned as is to the client. Otherwise, the server returns this response:

({
  status: 'error',
  error: {
    code: 'INTERNAL_SERVER_ERROR',
    message: 'An internal server error has occurred.'
  }
})

Customizing the error handler

Just as its HTTP version, the SocketIOController class supports an optional handleError to override the default error handler.

import { EventName, renderWebsocketError, SocketIOController, WebsocketContext, WebsocketErrorResponse } from '@foal/socket.io';

class PermissionDenied extends Error {}

export class WebsocketController extends SocketIOController implements ISocketIOController {
  @EventName('create user')
  createUser() {
    throw new PermissionDenied();
  }

  handleError(error: Error, ctx: WebsocketContext){
    if (error instanceof PermissionDenied) {
      return new WebsocketErrorResponse('Permission is denied');
    }

    return renderWebsocketError(error, ctx);
  }
}

Payload Validation

Foal provides a default hook @ValidatePayload to validate the request payload. It is very similar to its HTTP version @ValidateBody.

Server code

import { EventName, SocketIOController, WebsocketContext, WebsocketResponse } from '@foal/socket.io';

export class WebsocketController extends SocketIOController {

  @EventName('create product')
  @ValidatePayload({
    additionalProperties: false,
    properties: { name: { type: 'string' }},
    required: [ 'name' ],
    type: 'object'
  })
  async createProduct(ctx: WebsocketContext, payload: { name: string }) {
    const product = new Product();
    product.name = payload.name;
    await product.save();

    // Send a message to all clients.
    ctx.socket.broadcast.emit('refresh products');
    return new WebsocketResponse();
  }

}

Validation error response

({
  status: 'error',
  error: {
    code: 'VALIDATION_PAYLOAD_ERROR',
    payload: [
      // errors
    ]
  }
})

Unit Testing

Testing WebSocket controllers and hooks is very similar to testing their HTTP equivalent. The WebsocketContext takes three parameters.

Name	Type	Description
`eventName`	`string`	The name of the event.
`payload`	`any`	The request payload.
`socket`	`any`	The socket (optional). Default: `{}`.

Advanced

Multiple node servers

This example shows how to manage multiple node servers using a redis adapter.

npm install @socket.io/redis-adapter@7 redis@3

websocket.controller.ts

import { EventName, SocketIOController, WebsocketContext, WebsocketResponse } from '@foal/socket.io';
import { createAdapter } from '@socket.io/redis-adapter';
import { createClient } from 'redis';

export const pubClient = createClient({ url: 'redis://localhost:6379' });
export const subClient = pubClient.duplicate();

export class WebsocketController extends SocketIOController {
  adapter = createAdapter(pubClient, subClient);

  @EventName('create user')
  createUser(ctx: WebsocketContext) {
    // Broadcast an event to all clients of all servers.
    ctx.socket.broadcast.emit('refresh users');
    return new WebsocketResponse();
  }
}

Handling connection

If you want to run some code when a Websocket connection is established (for example to join a room or forward the session), you can use the onConnection method of the SocketIOController for this.

import { SocketIOController, WebsocketContext } from '@foal/socket.io';

export class WebsocketController extends SocketIOController {

  onConnection(ctx: WebsocketContext) {
    // ...
  }

}

The context passed in the onConnection method has an undefined payload and an empty event name.

Error-handling

Any errors thrown or rejected in the onConnection is sent back to the client. So you may need to add a try {} catch {} in some cases.

This error can be read on the client using the connect_error event listener.

socket.on("connect_error", () => {
  // Do some stuff
  socket.connect();
});

Custom server options

Custom options can be passed to the socket.io server as follows. The complete list of options can be found here.

import { SocketIOController } from '@foal/socket.io';

export class WebsocketController extends SocketIOController {

  options = {
    connectTimeout: 60000
  }

}

NodeJS - version 2.7 of Foal framework is here 🎉

Loïc Poullain — Mon, 13 Dec 2021 17:48:30 +0000

Version 2.7 of Foal has been released! Here are the improvements that it brings.

The body of `HttpResponse` can be typed

The HttpResponse class becomes generic so as to enforce the type of its body property if needed.

import { Get, HttpResponse } from '@foal/core';

import { Product } from '../entities';

export class AppController {
  @Get('/products')
  async products(): HttpResponse<Product[]> {
    const products = await Product.find({});
    return new HttpResponse(products);
  }
}

It also allows you to infer the type of the body in your tests:

Support for signed cookies

Starting from this version, you can sign cookies and read them through the signedCookies attribute.

import { Context, HttpResponseOK, Get, Post } from '@foal/core';

class AppController {
  @Get('/')
  index(ctx: Context) {
    const cookie1: string|undefined = ctx.request.signedCookies.cookie1;
    // Do something.
    return new HttpResponseOK();
  }

  @Post('/sign-cookie')
  index() {
    return new HttpResponseOK()
      .setCookie('cookie1', 'value1', {
        signed: true
      });
  }
}

In order to use signed cookies, you must provide a secret with the configuration key settings.cookieParser.secret.

Environment name can be provided via `NODE_ENV` or `FOAL_ENV`

Version 2.7 allows to you to specify the environment name (production, development, etc) with the FOAL_ENV environment variable.

This can be useful if you have third party libraries whose behavior also depends on the value of NODE_ENV (see Github issue here).

`foal generate entity` and `foal generate hook` support sub-directories

Example with entities (models)

foal g entity user
foal g entity business/product

Output

src/
 '- app/
  '- entities/
   |- business/
   | |- product.entity.ts
   | '- index.ts
   |- user.entity.ts
   '- index.ts

Example with hooks

foal g hook log
foal g hook auth/admin-required

Output

src/
 '- app/
  '- hooks/
   |- auth/
   | |- admin-required.hook.ts
   | '- index.ts
   |- log.hook.ts
   '- index.ts

New `afterPreMiddlewares` option in `createApp`

It is now possible to run a custom middleware after all internal Express middlewares of the framework.

This can be useful in rare situations, for example when using the RequestContext helper in Mikro-ORM.

const app = await createApp({
   afterPreMiddlewares: [
      (req, res, next) => {
         RequestContext.create(orm.em, next);
      }
   ]
})

DEV Community: Loïc Poullain

Foal version 5.2 is here 🎉

PasswordService and automatic password upgrade

New PasswordService

Automatic password upgrade

Deprecated functions

TypeORMStore now supports string user IDs

How it works

Migration

FoalTS - NodeJS framework - version 5.1 is out

Features

Enhancements

Node.JS - Foal framework version 4.5 is released 🎉

Asynchronous tasks

Social authentication for SPAs

Google social authentification

Logging improvements

CLI fixes

Global use of CLI deprecated

Node.JS - Version 4.3 of Foal framework has been released

Better CLI ouput when script arguments are invalid

[Fix] the logger no longer throws an error in development when the client request is interrupted

Foal version 3.0 is here 🚀

Full support of TypeORM v0.3

Code simplified

Authentication

File upload

Database models

Better typing

Validation with AJV

File upload

Authentication

GraphQL

Closer to JS ecosystem standards

Development command

Configuration through environment variables

null vs undefined values

More open to other ORMs

Shell scripts

Permission system

Smaller AWS S3 package

Dependencies updated and support of Node latest versions

Some bug fixes

Foal v2.11 has been released with better password management

Number of Iterations on Password Hashing Has Been Increased

How to use VSCode debugger with multiple Docker services

The Sample Application

The Node.JS code

The Docker configuration

Debugging the Application in Docker with VSCode

The debugger command

The Docker configuration

Running the debugger with VSCode

Debugging Multiple Docker Services

The Node.JS micro-service

The Docker configuration

Running multiple debuggers with VSCode

Version 2.10 of Foal is out!

@foal/cli package included by default as dev dependency

Preventing the npm run develop command to get stuck on some OS

Smaller main function

FoalTS 2022 survey is open!

FoalTS framework - Version 2.9 is here 🎉

New OAuth2 Twitter Provider

OAuth2 Providers support PKCE Code Flow

Support for version 15 of graphql and latest version of type-graphql

FoalTS framework - version 2.8 is here with complete Websocket support 🎉

In case you don't know...

Get Started

Server

Client

Architecture

Controllers and hooks

Contexts

Responses

Hooks

Summary table

Send a message

Broadcast a message

Grouping clients in rooms

`null` vs `undefined` values

`@foal/cli` package included by default as dev dependency

Preventing the `npm run develop` command to get stuck on some OS

Smaller `main` function

Support for version 15 of `graphql` and latest version of `type-graphql`

The body of `HttpResponse` can be typed

Environment name can be provided via `NODE_ENV` or `FOAL_ENV`

`foal generate entity` and `foal generate hook` support sub-directories

New `afterPreMiddlewares` option in `createApp`