FoalTS Documentation

Foal (or FoalTS) is a comprehensive Node.js framework designed for building web applications. It aims to provide a complete, integrated environment to reduce the need for searching and configuring disparate npm packages.

Key features included in the framework:

• CLI: Command-line interface for scaffolding and management.
• Testing Tools: Built-in support for reliable testing.
• Frontend Utilities: Tools to assist with client-side development.
• Advanced Authentication: Ready-to-use security components.
• ORM: Object-Relational Mapping for database interactions.
• API Support: Integrated GraphQL and Swagger/OpenAPI documentation.
• Cloud Utilities: AWS integration (e.g., @foal/aws-s3).
• TypeScript Native: Entirely written in TypeScript, providing static type-checking and excellent autocompletion.

Stateless CSRF protection is automatically managed when using @JWTRequired, setAuthCookie, and removeAuthCookie.

Enabling CSRF

To enable it, add the following to your configuration:

settings:
  jwt:
    csrf:
      enabled: true

How it works

1. When enabled, an additional XSRF-TOKEN cookie is sent to the client alongside the auth cookie.
2. This cookie contains a signed, stateless CSRF token with the same expiration as your JWT.
3. For every request, the @JWTRequired hook expects the client to include the value of the XSRF-TOKEN cookie in a header named XSRF-TOKEN.

FoalTS uses TypeORM as its default Object-Relational Mapping (ORM) layer. It is integrated by default in new projects, allowing you to create models, run migrations, and use the authentication system out of the box. TypeORM supports both Active Record and Data Mapper patterns and handles relations, transactions, and migrations.

import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';

@Entity()
export class User {

    @PrimaryGeneratedColumn()
    id: number;

    @Column()
    firstName: string;

    @Column()
    lastName: string;

}

When an error occurs in a controller or hook, it is converted into an HttpResponseInternalServerError (or your custom response from handleError).

In a hook's post function, you should check if the response is an error before executing logic that depends on a successful request. Use isHttpResponseInternalServerError(response) to detect these errors.

@Hook(() => response => {
  if (isHttpResponseInternalServerError(response)) {
    return;
  }

  // Else execute some logic.
})

To protect applications against common attacks, FoalTS automatically sets several security-related HTTP headers by default. These headers include:

• Strict-Transport-Security: max-age=31536000; includeSubDomains (Enforces HTTPS)
• X-Content-Type-Options: nosniff (Prevents MIME type sniffing)
• X-Frame-Options: SAMEORIGIN (Protects against clickjacking by restricting framing to the same origin)

Note that while these provide a layer of protection, they are not a complete security solution.

In Foal, a Controller is a class that receives HTTP requests and processes them. You define routes by adding methods to a controller class and decorating them with HTTP method decorators.

Available decorators include:

• @Get(path)
• @Post(path)
• @Patch(path)
• @Put(path)
• @Delete(path)

Each decorated method acts as a route handler for the specified path and HTTP method.

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

export class ApiController {
  @Get('/todos')
  async getTodos() {
    // handler logic
  }

  @Post('/todos')
  async postTodo(ctx: Context) {
    // handler logic
  }

  @Delete('/todos/:id')
  async deleteTodo(ctx: Context) {
    // handler logic
  }
}

Authentication in FoalTS follows a two-step pattern regardless of the application architecture (API, Web App, SPA, or Mobile):

Step 1: User Login

1. Verify credentials (e.g., email/password or social providers).
2. Generate a token (either a stateful Session Token or a stateless JSON Web Token).
3. Return the token to the client via a cookie, response body, or header.

Step 2: Subsequent Requests On every request, the server receives the token, validates it, and retrieves the associated user.

FoalTS supports multiple .env files based on the NODE_ENV environment variable.

If NODE_ENV is set to production, the framework will first look for values in .env.production. If a value is missing from that file, it will fall back to the default .env file.

You can reference environment variables in your configuration files using the env(VARIABLE_NAME) syntax (for YAML/JSON) or via the Env.get() method (for JS).

settings:
  jwt:
    secret: env(SETTINGS_JWT_SECRET)