9. Case Study: The Tax Calculation Server in NestJS

9.1. Recap of the Requirement

The server to be ported is an income tax calculation server (PHP) (see Introduction to the PHP7 Language Through Examples), architected in layers (Config / Entities / Model-DAO-Business / Controllers / Responses / Views), with a front-end controller (main.php) that routes incoming requests—all of which take the form URL (main.php?action=...)—to the appropriate controller based on the action. The goal of the port was to preserve this MVC architecture exactly as-is in NestJS, action by action, status code by status code, so that it would remain compatible with the HTML/TypeScript client already written for the PHP server.

9.2. The MVC architecture is carried over

The mapping between the two servers is direct:

• Config/config.json ↔ ConfigService;
• Entities/*.php ↔ entities/*.entity.ts (TaxAdminData, Simulation);
• Model/ServerDao*.php ↔ ServerDaoService (layer [DAO], Chapter 5);
• Model/ServerMetier.php ↔ ServerMetierService (layer [métier], line-by-line scope);
• Controllers/*Controller.php (one per action) ↔ one action controller per class TypeScript, dynamically selected by a register (ActionsRegistryService);
• Responses/*Response.php ↔ ResponseSenderService (jSON, XML) and HtmlViewRendererService (HTML);
• Views/*.php ↔ EJS templates (views/*.ejs), with the same Bootstrap layout.

Note: All actions on this server go through a single route, http://localhost:3000/main.php; the name of the requested action is always provided as a query string parameter, ?action=action-name—never in the URL path. This is a deliberate choice by URL that differs from the examples in the previous chapters (actions [/a01], [/m01]... routed by path segment), which is kept here exactly as it was on the original PHP server to remain compatible with the client that has already been written.

9.3. Project File Structure

Before going into detail about each layer, here is the complete directory structure of the nestjs-case-study project, as it appears after running npm install (the dist/ folder, generated by npm run build, and the node\_modules/ directory are not shown):

nestjs-etude-de-cas/
+-- .env.example
+-- .gitignore
+-- README.md
+-- create_dbimpots.sql
+-- nest-cli.json
+-- package.json
+-- tsconfig.json
+-- tsconfig.build.json
+-- data/
| +-- tax-admin-data.json
+-- Logs/
+-- public/
| +-- Resources/
| +-- logo.jpg
+-- views/
| +-- vue-authentification.ejs
| +-- vue-calcul-impot.ejs
| +-- vue-liste-simulations.ejs
| +-- vue-erreurs.ejs
| +-- partials/
| +-- bandeau.ejs
| +-- menu.ejs
| +-- authentification-form.ejs
| +-- calcul-impot-form.ejs
| +-- liste-simulations-table.ejs
+-- src/
    +-- main.ts
    +-- app.module.ts
    +-- main.controller.ts
    +-- config/
    | +-- config.service.ts
    +-- entities/
    | +-- simulation.entity.ts
    | +-- tax-admin-data.entity.ts
    | +-- exception-impots.ts
    +-- model/
    | +-- server-dao.interface.ts
    | +-- server-dao.service.ts
    | +-- server-metier.service.ts
    +-- actions/
    | +-- action-controller.interface.ts
    | +-- actions-registry.service.ts
    | +-- init-session.controller.ts
    | +-- authentifier-utilisateur.controller.ts
    | +-- calculer-impot.controller.ts
    | +-- afficher-calcul-impot.controller.ts
    | +-- lister-simulations.controller.ts
    | +-- supprimer-simulation.controller.ts
    | +-- fin-session.controller.ts
    | +-- admin-data.controller.ts
    +-- responses/
    | +-- response-sender.service.ts
    +-- views/
    | +-- view-models.ts
    | +-- html-view-renderer.service.ts
    +-- session/
    | +-- session.types.ts
    +-- utilities/
    | +-- logger.service.ts
    +-- filters/ (reserve, actuellement vide)

The role of each element:

• .env / .env.example — environment variables (port, session secret, MySQL and TAX_DATA_SOURCE parameters, etc.) read by ConfigService; .env is not versioned (.gitignore); .env.example serves as a template to copy (cp .env.example .env);
• .gitignore — excludes node_modules/, dist/, .env, and the repository logs;
• README.md — project documentation (installation, mapping between PHP and NestJS, annotated directory structure): this chapter summarizes and expands on that content;
• create_dbimpots.sql — script for creating the MySQL dbimpots-2019 database (tables tbtranches, tbconstantes..., used only when TAX_DATA_SOURCE=mysql);
• nest-cli.json, tsconfig.json, tsconfig.build.json — configuration of CLI, NestJS, and the TypeScript compiler, already discussed in previous chapters;
• package.json — dependencies (ejs, express-session, mysql2, js2xmlparser, dotenv...) and npm scripts (start, start:dev, build);
• data/tax-admin-data.json — backup tax dataset, used when TAX_DATA_SOURCE=json: no need to install MySQL to test the server;
• Logs/ — application log directory (logs.txt), written by LoggerService; created automatically at startup if it does not yet exist;
• public/Resources/logo.jpg — static image, served as-is by app.useStaticAssets(...) in main.ts, used by the banner in HTML views;
• views/ (at the project root) — the EJS templates and their partials, detailed further below in “Building HTML Pages”;
• src/main.ts — entry point: starts the NestJS server (see below);
• src/app.module.ts — root module: declares MainController as the sole controller and all of the application’s providers;
• src/main.controller.ts — the front-end controller, already described above;
• src/config/ — the application configuration (ConfigService), detailed further below;
• src/entities/ — the data classes (Simulation, TaxAdminData, ExceptionImpots), detailed further below;
• src/model/ — the [DAO] and [métier] layers;
• src/actions/ — one controller per action, the common interface ActionController, and the registry ActionsRegistryService;
• src/responses/ — response generation (jSON/XML) and handling (CORS (ResponseSenderService));
• src/views/ — Note: Do not confuse this with the views/ directory in the root directory. This folder contains only TypeScript, the construction of display templates (view-models.ts), and the selection/rendering of the view (EJS) (html-view-renderer.service.ts);
• src/session/ — TypeScript typing for the Express session (session.types.ts);
• src/utilities/ — logging (LoggerService);
• src/filters/ — reserved directory, currently empty: not yet used in this version of the project.

Two files deserve further mention: src/main.ts and src/app.module.ts, both specific to this project (beyond the framework already covered in previous chapters). Excerpt from src/main.ts:

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule);

  app.useStaticAssets(join(process.cwd(), 'public'));

  app.use(
    session({
      secret: process.env.SESSION_SECRET ?? 'change-moi-en-production',
      resave: false,
      saveUninitialized: false,
      cookie: { httpOnly: true, sameSite: 'lax', secure: false, path: '/' },
    }),
  );

  const port = Number(process.env.PORT ?? 3000);
  await app.listen(port);
}

Let’s comment on this code:

• line 4: app.useStaticAssets(join(process.cwd(), 'public')); — serves the files in the public/ folder as-is (here, public/Resources/logo.jpg) via a static route, without going through a NestJS controller;
• Line 6: app.use(session({...})); — installs the express-session middleware directly on the NestJS application: app.use(...) works here exactly as it does on a regular Express application, with NestJS built on top of it—this is what gives meaning to request.session in MainController and in each action controller;
• line 13: const port = Number(process.env.PORT ?? 3000); — the listening port, like the rest of the configurable settings, comes from an environment variable (in the .env file), with 3000 as the default value.

src/app.module.ts is the root module (already encountered in previous chapters): it declares MainController as the sole controller and lists all of the application’s providers in its providers array—the services (ConfigService, LoggerService, ServerDaoService, ServerMetierService, ResponseSenderService, HtmlViewRendererService, ActionsRegistryService) and the eight action controllers, all of which can be injected into one another using this same dependency injection mechanism.

9.4. The front-end controller

A single controller (NestJS, MainController) receives all requests to /main.php?action=... (@All('main.php')) : it retrieves the action parameter, checks the preconditions common to all actions (known action, session initialized, user authenticated), and then delegates to the controller for the relevant action.

Excerpt from src/main.controller.ts:

@Controller()
export class MainController {
  constructor(
    private readonly configService: ConfigService,
    private readonly responseSender: ResponseSenderService,
    private readonly actionsRegistry: ActionsRegistryService,
  ) {}

  @All('main.php')
  async handle(@Req() request: Request, @Res() response: Response): Promise<void> {
    const action = String(request.query.action ?? '').toLowerCase();

    if (!this.actionsRegistry.has(action)) {
       // ... status 102: invalid action
    }
    if (!request.session.type && action !== 'init-session') {
       // ... status 103: no current session
    }
    if (!request.session.user && action !== 'authentifier-utilisateur' && action !== 'init-session') {
       // ... status 104: user not authenticated
    }

    const controller = this.actionsRegistry.get(action);
    const result = await controller.execute(config, request, request.session);
     // ... constructing and sending the response (§6.7)
  }
}

Let’s comment on this code:

• line 1: [@Controller()] — this decorator marks the class as a controller NestJS -- used here without arguments, it does not set any common prefix: it is the route specified below, on the method itself, that will determine the exact prefix;
• line 3: [constructor(...)] — constructor injection of three @Injectable() providers: the configuration service, the response-sending service, and the action registry -- NestJS instantiates and provides them automatically, without having to write new ConfigService() anywhere;
• line 9: [@All('main.php')] — @All is a route decorator that associates the following method with all HTTP methods (GET, POST, PUT, DELETE...) to the given URL — here /main.php (this name, inherited from the PHP server, refers only to a path from URL to NestJS, not to an actual PHP file that is executed); this is what allows this same controller to handle both read actions (GET, e.g., init-session) and those that post data (POST, e.g., calculate-tax), with a single declared route;
• line 10: [@Req() request: Request, @Res() response: Response] — two parameter decorators we’ve already encountered: @Req() injects the complete request object (HTTP method, headers, query, body, session...), and @Res() injects the Express response object, providing full control over what is returned—necessary here because this controller must, depending on the situation, choose the status code HTTP and the response format itself (jSON, XML, or HTML), which a simple return statement would not allow for with such precision;
• line 11: [const action = String(request.query.action ?? '').toLowerCase();] — the action parameter is read manually from request.query — since we chose @Req() rather than the @Query('action') decorator seen in the previous chapter, the code must retrieve the value from the request object itself;
• Line 21: [const controller = this.actionsRegistry.get(action);] — once the preconditions have been verified, MainController does not process the action itself: it uses the action’s name to locate the corresponding action controller (see the next section) and delegates the work to it.

Note: This controller uses @Req() and @Res() rather than the individual decorators (@Query(), @Body(), etc.) from the previous chapter: it requires full access to the request (method, all parameters) and complete control over the response sent (choice of status code, format) —exactly as main.php did with the Symfony Request and Response objects.

9.5. An action controller

Each action has its own controller, which implements a common interface ActionController—the TypeScript counterpart to the PHP and InterfaceController interfaces. Here is a simplified version of the controller for the [calculer-impot] action:

Excerpt from src/actions/calculer-impot.controller.ts:

@Injectable()
export class CalculerImpotController implements ActionController {
  constructor(
    private readonly dao: ServerDaoService,
    private readonly métier: ServerMetierService,
  ) {}

  async execute(config, request, session): Promise<ActionResult> {
     // ... validation of posted parameters [marié, enfants, salaire]
     // (same numeric status codes as the original PHP controller)

    const taxAdminData = await this.dao.getTaxAdminData();
    const résultat = this.métier.calculerImpot(marié, enfants, salaire, taxAdminData);

    const simulations = session.simulations ?? [];
    simulations.push(Simulation.fromAttributes({ marié, enfants, salaire, ...résultat }));
    session.simulations = simulations;

    return { statusCode: 200, état: 300, content: { réponse: résultat }, headers: {} };
  }
}

Let’s break down this code:

• line 1: [@Injectable()] — first important point to note here: CalculerImpotController is a regular provider (@Injectable()), not a controller NestJS — it has neither @Controller() nor any routes (@Get, @Post...); only MainController (seen above) is recognized by the HTTP router in NestJS;
• Line 2: [export class CalculerImpotController implements ActionController] — this class implements the project-specific interface ActionController (defined in action-controller.interface.ts), which requires only one method: execute(...) -- this is a project convention, not a NestJS mechanism;
• line 3: [constructor(...)] — constructor injection of two services: DAO ([DAO] layer, access to tax data) and business logic ([métier] layer, pure calculation);
• line 8: [async execute(config, request, session): Promise<ActionResult>] — the method called by MainController.handle() (controller.execute(...), see above) -- its parameters are not NestJS decorators (@Body(), @Session()...) since this method is never called directly by the router HTTP: MainController already manually passes it the request and session that it itself received via @Req();
• line 12: [const taxAdminData = await this.dao.getTaxAdminData();] — retrieves the tax data (brackets, thresholds) needed for the calculation, via the [DAO] layer presented in the previous chapter;
• line 19: [return { statusCode: 200, état: 300, content: { réponse: résultat }, headers: {} };] — second important point: what execute() returns is not sent as-is to the browser—it is the project-specific structure ActionResult (statusCode, status, content, headers), which is parsed by MainController, then passed to ResponseSenderService, which constructs the HTTP response that is actually sent (jSON, XML, or HTML depending on the session type—see below).

This action is triggered by a request with the ID POST at http://localhost:3000/main.php?action=calculer-impot, with the three parameters "married," "children," and "salary" included in the request body (and not in the URL) — this is, in fact, the first thing that execute() checks, even before reading these parameters.

9.6. The Other Action Controllers

Each action has its own controller, all of which implement the same interface (the TypeScript counterpart to the PHP and InterfaceController interfaces)—excerpt from src/actions/action-controller.interface.ts:

export interface ActionResult {
  statusCode: number;
  état: number;
  content: Record<string, unknown>;
  headers: Record<string, string>;
}

export interface ActionController {
  execute(config: AppConfig, request: Request, session: AppSession): Promise<ActionResult>;
}

and all identified by their action names via a registry, which is itself injected by the constructor into MainController — excerpt from src/actions/actions-registry.service.ts:

constructor(
  initSession: InitSessionController,
  authentifierUtilisateur: AuthentifierUtilisateurController,
  calculerImpot: CalculerImpotController,
  listerSimulations: ListerSimulationsController,
  supprimerSimulation: SupprimerSimulationController,
  finSession: FinSessionController,
  afficherCalculImpot: AfficherCalculImpotController,
  adminData: AdminDataController,
) {
  this.registry = {
    'init-session': initSession,
    'authentifier-utilisateur': authentifierUtilisateur,
    'calculer-impot': calculerImpot,
    'lister-simulations': listerSimulations,
    'supprimer-simulation': supprimerSimulation,
    'fin-session': finSession,
    'afficher-calcul-impot': afficherCalculImpot,
    'get-admindata': adminData,
  };
}

Let’s break down this code:

• NestJS instantiates each of the eight action controllers (using @Injectable()) and passes them all, already constructed, to the constructor of ActionsRegistryService—which simply stores them in an associative array indexed by action name;
• this table (this.registry) serves exactly the same purpose as the table [actions] in Config/config.json on the PHP side, but without ever instantiating anything manually: has(action) and get(action) are the only two methods used by MainController.

The [calculer-impot] action has already been described in detail above. Here is what distinguishes each of the other seven action controllers:

• init-session.controller.ts — initializes the session response type (session.type = json, html, or xml); must be the very first action called (it is the only one exempted, by MainController, from the “no current session” check); requires the GET method and exactly two request parameters (action, type);
• authentifier-utilisateur.controller.ts — verifies the posted login/password pair against the list in config.users; constructs its status code by adding error bits (status += 2 if username is missing, status += 4 if password is missing) — same numerical logic as the original PHP validator;
• lister-simulations.controller.ts — the simplest of all: returns session.simulations ?? [], without any calculations;
• supprimer-simulation.controller.ts — performs a series of checks (method/number of parameters, presence of the “number” parameter, numeric syntax, index within the array bounds), accumulating the status code bit by bit at each successful step, then calls simulations.splice(number, 1) and re-saves the array to the session;
• afficher-calcul-impot.controller.ts — even shorter than lister-simulations: does absolutely nothing other than return status code 800, so that the client simply switches to a different view (back to the calculation form) without any server-side processing;
• admin-data.controller.ts — delegates directly to ServerDaoService.getTaxAdminData() and intercepts ExceptionImpots to return error status 1041; In calculer-impot, this is one of only two action controllers that injects the [DAO] layer into its constructor;

The case of src/actions/fin-session.controller.ts warrants closer examination due to a classic Express-Session pitfall:

async execute(config: AppConfig, request: Request, session: AppSession): Promise<ActionResult> {
  const method = request.method.toLowerCase();
  const nbParams = Object.keys(request.query).length;
  if (method !== 'get' || nbParams !== 1) {
    return {
      statusCode: 400,
      état: 401,
      content: { réponse: "GET requis avec le seul paramètre [action] dans l'URL" },
      headers: {},
    };
  }
  const type = session.type;
  await new Promise<void>((resolve) => session.regenerate(() => resolve()));
  request.session.type = type;
  return {
    statusCode: 200,
    état: 400,
    content: { réponse: 'session supprimée' },
    headers: {},
  };
}

Let’s comment on this code:

• line 9: const type = session.type; — we store the response type (json/html/xml) before destroying the session, since we’ll need to restore it in the new one;
• line 10: await new Promise<void>((resolve) => session.regenerate(() => resolve())); — a tricky part of this controller: session.regenerate(callback), provided by express-session, is a callback method, not a Promise; so we wrap it in a Promise to be able to await it like the rest of the code; regenerate() clears the current session and assigns it a brand-new identifier (the equivalent of Symfony’s session destruction);
• line 11: request.session.type = type; — second tricky point: after regenerate(), request.session points to a brand-new session instance; the old session reference, captured in the execute() parameters before the call, is now orphaned—which is why the type is reassigned to request.session rather than session; otherwise, it would be silently lost.

9.7. The [DAO] layer

ServerDaoService (§5.1) provides tax data (brackets, thresholds) to the business layer, either from a jSON file (useful for testing without a database) or from MySQL with mysql2, depending on a configuration parameter.

Excerpt from src/model/server-dao.interface.ts—a minimal contract, a single method that every implementation of the [DAO] layer must provide:

export interface IServerDao {
  getTaxAdminData(): Promise<TaxAdminData>;
}

Excerpt from src/model/server-dao.service.ts, the only implementation of this contract in this project:

@Injectable()
export class ServerDaoService implements IServerDao {
  constructor(private readonly configService: ConfigService) {}

  async getTaxAdminData(): Promise<TaxAdminData> {
    const { taxDataSource } = this.configService.config;
    if (taxDataSource === 'mysql') {
      return this.getTaxAdminDataFromMysql();
    }
    return this.getTaxAdminDataFromJson();
  }

  private async getTaxAdminDataFromJson(): Promise<TaxAdminData> {
    const { jsonTaxDataFile } = this.configService.config;
    try {
      const fileContents = fs.readFileSync(jsonTaxDataFile, 'utf-8');
      const attributes = JSON.parse(fileContents);
      return TaxAdminData.fromAttributes(attributes);
    } catch (ex) {
      throw new ExceptionImpots(
        `Le fichier de données fiscales [${jsonTaxDataFile}] n'a pu être exploité : ${(ex as Error).message}`,
      );
    }
  }

  private async getTaxAdminDataFromMysql(): Promise<TaxAdminData> {
    const { mysql: dbConfig } = this.configService.config;
    let connection: mysql.Connection | null = null;
    try {
      connection = await mysql.createConnection({
        host: dbConfig.host,
        port: dbConfig.port,
        database: dbConfig.database,
        user: dbConfig.user,
        password: dbConfig.password,
      });

       // tax brackets (table tbtranches)
      const [tranches] = await connection.query<RowDataPacket[]>(
        'select limites, coeffR, coeffN from tbtranches order by id',
      );
      const limites = tranches.map((row) => Number(row.limites));
      const coeffR = tranches.map((row) => Number(row.coeffR));
      const coeffN = tranches.map((row) => Number(row.coeffN));

       // calculation constants (table tbconstantes)
      const [constantesRows] = await connection.query<RowDataPacket[]>(
        'select plafondQfDemiPart, ... from tbconstantes limit 1',
      );
      const row = constantesRows[0];

      return TaxAdminData.fromAttributes({
        limites, coeffR, coeffN,
        plafondQfDemiPart: Number(row.plafondQfDemiPart),
         // ... same Number(...) conversions for the other eight constants
         // (see the source file for the complete list)
      });
    } catch (ex) {
      throw new ExceptionImpots(`[mysql] ${(ex as Error).message}`);
    } finally {
      if (connection) {
        await connection.end();
      }
    }
  }
}

Let’s comment on this code:

• async getTaxAdminData(): Promise<TaxAdminData> { if (taxDataSource === 'mysql') ... } — the decision-making process fits into a single line: depending on config.taxDataSource (read from the environment variable TAX_DATA_SOURCE), data is fetched from either the jSON file or the MySQL file, but the contract exposed to the rest of the application (IServerDao) remains unchanged — CalculerImpotController and AdminDataController have no idea which source is actually being used;
• getTaxAdminDataFromJson() — reads and parses data/tax-admin-data.json synchronously (fs.readFileSync); any error (missing file, invalid jSON) is intercepted and logged as a ExceptionImpots, with an explicit message—never a raw Node exception, which would not be properly propagated back to the client;
• getTaxAdminDataFromMysql() — opens a MySQL connection on every call using mysql2/promise (no connection pool is reused: consistent with the absence of a Redis cache noted in README, each query re-checks everything); executes the two SQL queries (slices, then constants), reconstructs a TaxAdminData from the retrieved rows, and systematically closes the connection in a finally block, regardless of whether the read was successful or not;
• both private methods return the same type (Promise<TaxAdminData>), which allows getTaxAdminData() to remain a simple facade, without any business logic of its own.

9.8. The [métier] layer

ServerMetierService is unaware of HTTP, sessions, or the database: it is a line-by-line port of the tax calculation from the PHP server, pure and testable independently of the rest.

Excerpt from src/model/server-metier.service.ts:

@Injectable()
export class ServerMetierService {
  calculerImpot(
    marié: string,
    enfants: number,
    salaire: number,
    taxAdminData: TaxAdminData,
  ): ResultatCalculImpot {
     // ... same algorithm as Model/ServerMetier.php: family quotient,
     // cap, discount, reduction
  }

  private getRevenuImposable(salaire: number, taxAdminData: TaxAdminData): number {
    let abattement = 0.1 * salaire;
    if (abattement > taxAdminData.abattementDixPourcentMax) {
      abattement = taxAdminData.abattementDixPourcentMax;
    }
    if (abattement < taxAdminData.abattementDixPourcentMin) {
      abattement = taxAdminData.abattementDixPourcentMin;
    }
    return Math.floor(salaire - abattement);
  }
}

• line 1: [@Injectable()] — once again, this same decorator, for the same reason as elsewhere in this chapter: without it, NestJS would not be able to instantiate ServerMetierService or inject it into CalculerImpotController above;
• line 2: [export class ServerMetierService {] — from here on, apart from this first decorator, the code is no longer specific to NestJS: calculerImpot(...) and getRevenuImposable(...) are standard TypeScript code—a line-by-line port of the PHP algorithm, without HTTP or a database.

9.9. The application configuration

src/config/config.service.ts combines, into a single NestJS service, what was previously split between Config/config.json and Config/database.json on the PHP side — with the expected difference that sensitive configuration (passwords, session secrets) now comes from environment variables (.env file), rather than from a versioned jSON file:

@Injectable()
export class ConfigService {
  readonly config: AppConfig;

  constructor() {
    this.config = {
      corsAllowed: (process.env.CORS_ALLOWED ?? 'true') !== 'false',
      actions: {
        'init-session': 'InitSessionController',
         // ... one entry per action (see actions-registry.service.ts),
         // retained for reference purposes only
      },
      types: ['json', 'html', 'xml'],
      users: [{ login: 'admin', passwd: 'admin' }],
      taxDataSource: (process.env.TAX_DATA_SOURCE as 'json' | 'mysql') ?? 'json',
      jsonTaxDataFile: path.join(process.cwd(), 'data', 'tax-admin-data.json'),
      mysql: {
        host: process.env.DB_HOST ?? 'localhost',
        port: Number(process.env.DB_PORT ?? 3306),
        database: process.env.DB_NAME ?? 'dbimpots-2019',
        user: process.env.DB_USER ?? 'admimpots',
        password: process.env.DB_PASSWORD ?? 'mdpimpots',
      },
      logsFilename: path.join(process.cwd(), 'Logs', 'logs.txt'),
      sessionSecret: process.env.SESSION_SECRET ?? 'change-moi-en-production',
      vues: {
        'vue-authentification': [700, 221, 400],
        'vue-calcul-impot': [200, 300, 341, 350, 800],
        'vue-liste-simulations': [500, 600],
      },
      vueErreurs: 'vue-erreurs',
      viewsDir: path.join(process.cwd(), 'views'),
    };
    const logsDir = path.dirname(this.config.logsFilename);
    if (!fs.existsSync(logsDir)) {
      fs.mkdirSync(logsDir, { recursive: true });
    }
  }
}

Let’s comment on this code:

• actions: { ... } — this table is kept solely for documentation purposes (it accurately describes the original architecture): the actual routing of actions does not rely on it; instead, it is handled through dependency injection in ActionsRegistryService;
• taxDataSource: (process.env.TAX_DATA_SOURCE as ...) ?? 'json' — read from the environment variable TAX_DATA_SOURCE, this field selects the source of the tax data used by ServerDaoService (see above);
• views: { ... } — associates each EJS template name with the list of response reports that should display it (for example, vue-calcul-impot for reports 200, 300, 341, 350, 800); HtmlViewRendererService (see “Building HTML Pages”) uses this table to select the view to render;
• vueErreurs: 'error-view' — the fallback view, displayed whenever no view entries match the current report;
• final line: if (!fs.existsSync(logsDir)) { fs.mkdirSync(logsDir, { recursive: true }); } — Upon creation, the service itself creates the Logs/ folder if it does not yet exist, so that LoggerService can always write to it without ever having to worry about it.

9.10. Entities, the session, and logs

src/entities/ contains three data classes, defined in Entities/*.php. Excerpt from simulation.entity.ts—a calculation simulation, stored in session.simulations:

export class Simulation {
  marié: string;
  enfants: number;
  salaire: number;
  impôt: number;
  surcôte: number;
  décôte: number;
  réduction: number;
  taux: number;

  static fromAttributes(attributes: Partial<Simulation>): Simulation {
    const simulation = new Simulation();
    Object.assign(simulation, attributes);
    return simulation;
  }
}

Excerpt from tax-admin-data.entity.ts—the tax brackets and calculation constants read by the [DAO] layer:

export class TaxAdminData {
  limites: number[] = [];
  coeffR: number[] = [];
  coeffN: number[] = [];
  plafondQfDemiPart = 0;
   // ... the eight other calculation constants (see the source file)

  static fromAttributes(attributes: Partial<TaxAdminData>): TaxAdminData {
    const entity = new TaxAdminData();
    Object.assign(entity, attributes);
    return entity;
  }
}

and exception-impots.ts — a typed application exception, raised by the [DAO] layer in the event of an inaccessible data source (unreadable jSON file, failed MySQL connection...), and intercepted by the action handlers that require it (calculer-impot, get-admindata):

export class ExceptionImpots extends Error {
  constructor(message: string, public readonly code: number = 0) {
    super(message);
    this.name = 'ExceptionImpots';
  }
}

src/session/session.types.ts is not a service: it is a type declaration that extends the express-session module, so that TypeScript can access the application-specific content (session type, authenticated user, saved simulations):

declare module 'express-session' {
  interface SessionData {
    type?: 'json' | 'html' | 'xml';
    user?: boolean;
    simulations?: Simulation[];
  }
}

export type AppSession = Session & Partial<SessionData>;

Note: This technique—module extension (`declare module 'express-session'`)—is what allows you to write `request.session.simulations` or `session.user` elsewhere in the project without the `TypeScript` compiler raising an error; AppSession, the actual type of req.session used throughout the action controllers, is derived directly from this.

Finally, src/utilities/logger.service.ts logs everything the server does (new request, requested action, selected controller, returned response, etc.) in Logs/logs.txt:

@Injectable()
export class LoggerService {
  constructor(private readonly configService: ConfigService) {}

  write(message: string): void {
    const timestamp = new Date().toISOString().replace('T', ' ').replace('Z', '');
    fs.appendFile(
      this.configService.config.logsFilename,
      `${timestamp} : ${message}\n`,
      () => { /* log writing in best-effort mode, as in PHP */ },
    );
  }
}

Note: Writing is performed in best-effort mode (asynchronous fs.appendFile, without waiting for or verifying the result): a problem writing to the logs should never cause a request to fail—exactly the approach taken by Utilities/Logger.php on the PHP side.

9.11. The responses jSON, XML, and HTML

ResponseSenderService constructs the response jSON or XML (using the js2xmlparser library), replicates the handling of CORS by the original server PHP (Access-Control-Allow-* headers only for the localhost origin), and handles the special case of the OPTIONS method (CORS preflight).

Excerpt from src/responses/response-sender.service.ts, which actually constructs this response:

async send(
  request: Request, response: Response, config: AppConfig,
  statusCode: number, content: Record<string, unknown>,
  headers: Record<string, string>, type: 'json' | 'html' | 'xml',
): Promise<void> {
  let body: string;
  let contentType: string;
  switch (type) {
    case 'xml':
      body = js2xmlparser.parse('root', content);
      contentType = 'application/xml';
      break;
    case 'html':
      body = await this.htmlViewRenderer.render(content, request);
      contentType = 'text/html';
      break;
    case 'json':
    default:
      body = JSON.stringify(content);
      contentType = 'application/json';
      break;
  }
  headers = { ...headers, 'content-type': contentType };
  this.sendResponse(request, response, statusCode, body, headers, config);
  this.logger.write(`réponse=${JSON.stringify(content)}\n`);
}

private sendResponse(
  request: Request, response: Response, statusCode: number,
  content: string, headers: Record<string, string>, config: AppConfig,
): void {
  if (config.corsAllowed) {
    const origin = request.headers.origin ?? '';
    if (origin.startsWith('http://localhost') || origin.startsWith('https://localhost')) {
      headers = {
        ...headers,
        'Access-Control-Allow-Origin': origin,
        'Access-Control-Allow-Headers': 'Accept, Content-Type',
        'Access-Control-Allow-Methods': 'GET, POST',
        'Access-Control-Allow-Credentials': 'true',
      };
    }
  }
  const method = request.method.toLowerCase();
  if (method === 'options') {
    content = '';
    statusCode = 200;
  }
  Object.entries(headers).forEach(([name, value]) => response.setHeader(name, value));
  response.status(statusCode).send(content);
}

Let’s comment on this code:

• switch (type) { ... } — the three response formats are constructed here, and only here: JSON by JSON.stringify, XML by the js2xmlparser library (which transforms the content object into a XML document, with the <root> element as the root), and HTML by delegating entirely to HtmlViewRendererService.render(...), detailed further below;
• this.logger.write(response=${JSON.stringify(content)}); — in HTML mode as well, it is the application content of the response (content) that is logged, never the entire HTML page produced—as HtmlResponse.php did;
• in sendResponse(...), the check origin.startsWith('http://localhost') || origin.startsWith('https://localhost') exactly replicates the policy CORS of the original server PHP (ParentResponse::sendResponse): only localhost origins receive Access-Control-Allow-* headers; never an arbitrary domain;
• if (method === 'options') { content = ''; statusCode = 200; } — special case of the CORS preflight: for a OPTIONS request, only the headers matter; the response body is cleared and the status code is forced to 200, regardless of the requested processing.

For the type=html mode, HtmlViewRendererService replicates the view selection logic of the PHP server: each response status corresponds to a view, selected from a configuration table, with a fallback to a generic error page if no view matches. Each view is a EJS template (views/*.ejs), a direct translation of the original PHP files, powered by a “display template” generated by a dedicated function—the same principle as the getModelForThisView(...) / PHP view pair, with the added benefit of automatic escaping of displayed values.

Note: For those who have already encountered NestJS elsewhere: this HTML rendering does not use the @Render() decorator provided by NestJS to associate a controller method with a view engine (EJS, Handlebars, Pug...) -- This mechanism requires a traditional NestJS controller with one route per view, which is incompatible with this server’s single front-end controller. ejs.renderFile(...) is therefore called directly, manually, within HtmlViewRendererService, and then the resulting HTML is sent as plain text via @Res() (see above): a perfectly valid alternative for rendering views using NestJS, but without going through this specific decorator.

9.12. Building HTML Pages

Let’s take a closer look at the type=html mode, whose mechanism is broken down into three distinct files: the selection and rendering of the view (src/views/html-view-renderer.service.ts), the construction of the “display template” specific to each view (src/views/view-models.ts), and the templates themselves (views/*.ejs and views/partials/*.ejs, in the project root—not to be confused with the src/views/ folder, which contains only TypeScript).

Excerpt from src/views/html-view-renderer.service.ts:

@Injectable()
export class HtmlViewRendererService {
  constructor(private readonly configService: ConfigService) {}

  async render(content: Record<string, unknown>, request: Request): Promise<string> {
    const { vues, vueErreurs, viewsDir } = this.configService.config;
    const état = content['état'] as number;

    const nomVue = Object.keys(vues).find((vue) => vues[vue].includes(état)) ?? vueErreurs;

    const logo = buildLogoPath(request);

    let modèle: unknown;
    switch (nomVue) {
      case 'vue-authentification':
        modèle = buildAuthentificationModel(état, request);
        break;
      case 'vue-calcul-impot':
        modèle = buildCalculImpotModel(état, request, content);
        break;
      case 'vue-liste-simulations':
        modèle = buildListeSimulationsModel(content);
        break;
      case 'vue-erreurs':
      default:
        modèle = buildErreursModel(content);
        break;
    }

    const templateFile = path.join(viewsDir, `${nomVue}.ejs`);
    return ejs.renderFile(templateFile, { modèle, logo }, { views: [viewsDir, path.join(viewsDir, 'partials')] });
  }
}

Let's comment on this code:

• const nomVue = Object.keys(views).find((view) => views[vue].includes(status)) ?? vueErreurs; — the key line of the entire mechanism: we search the config.vues table (see above) for the name of the view whose list of statuses contains the current response status; if none match—including, as README points out, a success status without a dedicated view such as get-admindata/1000—we fall back to vueErreurs (error view), which follows exactly the same logic as HtmlResponse::send() on the PHP side;
• const logo = buildLogoPath(request); — the logo path is recalculated for each request based on the requested URL (see view-models.ts below), to ensure it remains correct even if the application is deployed in a subdirectory;
• switch (nomVue) { case 'authentication-view': template = buildAuthentificationModel(...); ... } — once the view is selected, the corresponding template-building function is called (detailed below); it is this template, and this template alone, that the EJS template will display;
• return ejs.renderFile(templateFile, { template, logo }, { views: [viewsDir, path.join(viewsDir, 'partials')] }); — the actual call to EJS: ejs.renderFile(...) reads the corresponding .ejs file, executes it with the template and logo variables in its context, and returns the resulting HTML as a string — the views option tells EJS the two directories where to look for a template included by name (the views folder and its partials/ subfolder).

src/views/view-models.ts defines a function for constructing a template by view—the TypeScript equivalent of the function getModelForThisView(...) present in each of the original PHP views (Views/view-*.php). Here is an excerpt from the simplest of the four, buildAuthentificationModel:

export function buildAuthentificationModel(
  état: number,
  request: Request,
): AuthentificationModel {
  const modèle: AuthentificationModel = { login: '', error: false, erreurs: [] };
  switch (état) {
    case 700:
    case 400:
      modèle.login = '';
      modèle.error = false;
      break;
    case 221:
      modèle.login = String(request.body?.user ?? '');
      modèle.error = true;
      modèle.erreurs = ["Echec de l'authentification"];
      break;
  }
  return modèle;
}

and the most complex one, buildCalculImpotModel, which must handle three distinct cases:

export function buildCalculImpotModel(
  état: number,
  request: Request,
  content: Record<string, unknown>,
): CalculImpotModel {
  const modèle: CalculImpotModel = {
    success: false, error: false, checkedOui: false, checkedNon: false,
    enfants: '', salaire: '', erreurs: [],
    optionsMenu: {
      'Liste des simulations': 'main.php?action=lister-simulations',
      'Fin de session': 'main.php?action=fin-session',
    },
  };
  switch (état) {
    case 200:
    case 800:
      modèle.success = false;
      modèle.error = false;
      modèle.checkedNon = true;
      modèle.checkedOui = false;
      modèle.enfants = '';
      modèle.salaire = '';
      break;
    case 300: {
      const réponse = content.réponse as Record<string, unknown>;
      modèle.success = true;
      modèle.error = false;
      modèle.impôt = `Montant de l'impôt : ${réponse.impôt} euros`;
      modèle.décôte = `Décôte : ${réponse.décôte} euros`;
      modèle.réduction = `Réduction : ${réponse.réduction} euros`;
      modèle.surcôte = `Surcôte : ${réponse.surcôte} euros`;
      modèle.taux = `Taux d'imposition : ${(réponse.taux as number) * 100} %`;
      const marié = request.body?.['marié'];
      modèle.checkedOui = marié === 'oui';
      modèle.checkedNon = marié !== 'oui';
      modèle.enfants = String(request.body?.enfants ?? '');
      modèle.salaire = String(request.body?.salaire ?? '');
      break;
    }
    case 341:
    case 350: {
      const marié = request.body?.['marié'];
      modèle.checkedOui = marié === 'oui';
      modèle.checkedNon = marié !== 'oui';
      modèle.enfants = String(request.body?.enfants ?? '');
      modèle.salaire = String(request.body?.salaire ?? '');
      modèle.success = false;
      modèle.error = true;
      modèle.erreurs = [String(content.réponse)];
      break;
    }
  }
  return modèle;
}

Let’s comment on this code:

• status codes 200 and 800 (empty form, arrival at the view, or return from display-calculate-tax) — all fields in the model are reset to empty, as if the form had never been filled out;
• status 300 (successful calculation) — const response = content.réponse as Record<string, unknown>; retrieves the result returned by CalculerImpotController (tax, discount, reduction, surcharge, rate) and constructs the five sentences displayed in the success banner; the form is repopulated with the posted values (request.body), so that the user can review their input alongside the result;
• reports 341 and 350 (database—or Redis—down) — same re-display of the posted form, but with modèle.error = true and the error message returned by the [DAO] layer placed in modèle.erreurs;
• optionsMenu: { ... } — the side menu (part of menu.ejs, see below) is state-independent: it is always present, with the same two options, regardless of the calculation result.

The remaining two functions follow the same principle:

• buildListeSimulationsModel(content) — the shortest of the four: simulations: (content.réponse as SimulationRow[]) ?? [], supplemented by the same side menu as buildCalculImpotModel (this time with “Tax Calculation” and “End Session”);
• buildErreursModel(content) — builds the list of messages displayed by the generic "error-view" view; handles a very specific case inherited from the original PHP: else if (response !== null && typeof response === 'object') { errors = [JSON.stringify(réponse)]; }, in the event that a successful status without a dedicated view (such as get-admindata/1000) nevertheless falls back to this error view—the original PHP would then display the object via its __toString() method; JSON.stringify is the equivalent of TypeScript;
• buildLogoPath(request) — const root = pathname.replace(/\/[^/]*$/, ''); return ${root}/Resources/logo.jpg; : reconstructs the logo path from the current URL directory (without the script name), so that the banner remains correct even if the application is deployed in a subdirectory — directly ported from Views/v-bandeau.php.

The four views/*.ejs templates are direct translations of the original PHP files (Views/vue-*.php), with the same Bootstrap 4.1.3 layout. The most complete excerpt, vue-calcul-impot.ejs:

<%# equivalent to Views/vue-calcul-impot.php %>
<!doctype html>
<html lang="fr">
  <head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" ...>
    <title>Application impots</title>
  </head>
  <body>
    <div class="container">
      <%- include('partials/bandeau', { logo: logo }) %>
      <div class="row">
        <div class="col-md-3">
          <%- include('partials/menu', { modèle: modèle }) %>
        </div>
        <div class="col-md-9">
          <%- include('partials/calcul-impot-form', { modèle: modèle }) %>
        </div>
      </div>
      <% if (modèle.success) { %>
      <div class="row">
        <div class="col-md-9">
          <div class="alert alert-success" role="alert">
            <%= modèle.impôt %><br>
            <%= modèle.décôte %><br>
            ...
          </div>
        </div>
      </div>
      <% } %>
      <% if (modèle.error) { %>
        ... (meme principe, alert-danger, boucle sur modèle.erreurs)
      <% } %>
    </div>
  </body>
</html>

Let’s comment on this template:

• line 1: <%# ... %> — a EJS comment, never sent to the browser;
• <%- include('partials/bandeau', { logo: logo }) %> — includes a partial template, with the variables we want to explicitly pass to it (here, logo); note: <%- %> displays the result without escaping it — used here solely to insert HTML already constructed by include(...), never for user-entered data;
• <% if (modèle.success) { %> ... <% } %> — EJS control block (<% %>, without a hyphen): JavaScript executed during rendering, which itself produces no output; here, the “result” section appears in the final HTML only if modèle.success is true;
• <%= modèle.impôt %> — escaped display (<%= %>, with the equal sign): this is the form used for any data that may contain user input (calculation results, re-displayed login, error messages) — EJS automatically escapes special characters, unlike the <?= ?> in the original PHP, which did not.

The other three views and the five partials (views/partials/) follow the same principles:

• vue-authentification.ejs — the login form; includes partials/header and partials/authentication-form, then displays the list modèle.erreurs if modèle.error;
• vue-liste-simulations.ejs — includes partials/header, partials/menu, and partials/simulation-list-table;
• vue-erreurs.ejs — the fallback view: partials/header, partials/menu, followed by a simple loop <% modèle.erreurs.forEach(function(error) { %><li><%= error %></li><% }) %>;
• partials/bandeau.ejs — the logo and the “Calculate Your Tax” title, common to all views except the authentication view, which also includes them;
• partials/menu.ejs — <% Object.keys(modèle.optionsMenu).forEach(function(text) { %><a href="<%= modèle.optionsMenu[texte] %>"><%= text %></a><% }) %>: the side menu, which is entirely controlled by the optionsMenu table created in view-models.ts—so adding a menu option only requires changing the model, never this template;
• partials/authentification-form.ejs — the Bootstrap login form, with value="<%= modèle.login %>" to redisplay the last login entered in case of failure;
• partials/calcul-impot-form.ejs — the calculation form; note <%- modèle.checkedOui ? 'checked="checked"' : '' %>: a deliberate and safe use of <%- %>, since the inserted string (checked="checked" or empty) is set on the server side and is never constructed from user input;
• partials/liste-simulations-table.ejs — the simulation table, one row per item in modèle.simulations, with a “Delete” link to main.php?action=delete-simulation&number=... for each row.

Note: Unlike the original PHP, which re-injected certain values without escaping them via <?= ?> (a reflected vulnerability in XSS, exploitable notably via the authentication form), the EJS templates in this project consistently use <%= %> for all user-supplied data (login, children, salary, error messages). The few instances of <%- %> in this project are used only to include a partial or to insert an attribute constructed on the server side from a fixed value—never user input: this behavior is functionally identical to the PHP server, without replicating its vulnerability.

9.13. Execution

At the root of the [nestjs-etude-de-cas] folder:

npm install
cp .env.example .env
npm run start:dev

The server then listens on http://localhost:3000. The jSON mode, used by the TypeScript client, is tested with:

http://localhost:3000/main.php?action=init-session&type=json

and the HTML mode, directly in the browser, with:

http://localhost:3000/main.php?action=init-session&type=html

In both cases, the same action parameter determines the processing performed (in this case, init-session, which must be the very first action called since it initializes the session), and the type parameter determines the response format—other actions are tested in the same way, simply by changing the value of action (for example, &action=calculer-impot, to POST, with the parameters “married,” “children,” and “salary” submitted).

Open a browser and request the URL [http://localhost:3000/main.php?action=init-session&type=html]

The login credentials are admin / admin. Submit the form.

Fill out the form and then submit it:

Run several simulations, then request the [Liste des simulations]:

Delete both simulations:

End the session: