Exemple article

Avec NodeJS v18, il est possible d’écrire ses tests sans librairie externe grâce au module node:test

Ce nouveau module permet de définir un jeu de test, que l’on pourra jouer via la commande [node --test](<https://nodejs.org/api/test.html#running-tests-from-the-command-line&gt;).

Toujours dans l’idée d’utiliser le moins de dépendances externes, un bon module pour faire des assertions est [node:assert/strict](<https://nodejs.org/api/assert.html#strict-assertion-mode&gt;).

En prenant un exemple

Dans un fichier index.js

export function canRegister({ age, country, job }) {
  return age >= 18 && country === 'US' && job === 'engineer';
}

En utilisant le test runner de Node, on peut écrire le test suivant dans le fichier index.test.js

import assert from 'node:assert/strict';
import { describe, it } from 'node:test';

import { canRegister } from './index.js';

describe('canRegister', () => {
  it('returns true when age is 18, country is US, and job is engineer', () => {
    const result = canRegister({ age: 18, country: 'US', job: 'engineer' });
    assert.strictEqual(result, true);
  });

  it('returns false when age is 17, country is US, and job is engineer', () => {
    const result = canRegister({ age: 17, country: 'US', job: 'engineer' });
    assert.strictEqual(result, false);
  });
});

À noter qu’il est possible de skip un test avec la syntaxe suivante it([name], { skip: true }[, fn]) ou en ajoutant it.skip

Et on exécute le test avec la commande node --test

node --test va chercher récursivement les fichiers dont le nom est test.js , monfichier.test.js ou encore test-monfichier.js (plus de détail dans la doc). Il est aussi possible de passer un fichier en argument à la commande node --test.

TAP version 13
# Subtest: /node-test-runner/index.test.js
ok 1 - /node-test-runner/index.test.js
  ---
  duration_ms: 44.544125
  ...
1..1
# tests 1
# pass 1
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 47.909458

On obtient un retour au format TAP (Test Anything Protocol) https://testanything.org/tap-specification.html ce qui nous permettra de pouvoir utiliser des reporters compatibles avec ce standard.

Par exemple, le module tap-spec permet d’obtenir le rendu suivant :

Il suffit de piper le résultat de node --test dans tape-spec : node --test | tap-spec

Une liste de reporters est disponible ici https://github.com/ljharb/tape#pretty-reporters

Spy, stub et mocks

Contrairement à jest, node:test ne permet pas de faire des spy ou mocks de modules.

Il est possible d’utiliser les librairies suivantes :

• spying et stubbing avec sinon
• snapshots avec snapshot-assertion

Passwords must never be stored in clear text in the database. If they were, attackers would be able to steal them if the database ever gets compromised.

To avoid this, two actions are necessary to store a password securely: hashing and salting.

Hashing

A hash function is a one-way function that maps one value to another value of fixed size. Secure hash functions are unidirectional: it is not possible to “decrypt” the generated hash and get the original value. They are used to generate password hashes.

When a user first registers for the application, his or her password is hashed and the result is stored in the database. Then, when the user tries to log in again, the submitted password is also hashed and the result is compared to the value stored in the database. If the values are equal, the password is correct. If not, the password is incorrect. This way, the password is not stored in the database in clear text and if the database is compromised, an attacker will not be able to read the passwords.

Note: Not all hash algorithms are secure for storing passwords. In particular, MD5 or SHA-1 are not suitable because the original password can potentially be guessed by studying the hash. According to OWASP, the currently secure hash functions for storing passwords are Argon2id, bcrypt, scrypt and PBKDF2.

Salting

Hashing passwords is however not enough. An attacker can defeat one-way hashes with pre-computation attacks.

If an attacker pre-computes hashes of common passwords and builds what is called a rainbow table, they will be able to retrieve some of the original passwords by comparing the table’s hashes with those stored in the database.

To avoid this, a random string, a salt, can be generated for each password and used during the hashing process. In this case, not only does the hash function take the password as input, but it also takes the salt. This implies that two identical passwords will result in a different hash because they will have a different randomly generated salt used to generate the hash.

More precisely, when a user subscribes to the application for the first time, a salt is generated. This salt and the password are next combined and hashed. The result is stored in the database along with the salt. Then, when the user tries to log in again, the salt is retrieved from the database and combined with the submitted password to be hashed. The resulted hash is then compared to the value stored in the database.

In this way, if an attacker wants to pre-computes hashes, they will have to pre-compute a hash table for each salt (i.e, each password stored in the database), which considerably increases the required capacity and computing time, making password theft more difficult.

When properly implemented and with the right algorithms, these two techniques, salting and hashing, thus allow passwords to be securely stored in the database.

Bonus: algorithm rotation

Usually, the salt and the hash are not the only two values that are stored in the database. The algorithm and some additional information are also present with them.

For example, in the case of the Django framework, this is how a password stored in the database might look like:

pbkdf2_sha256$150000$B6U8ZKsV963hFZLlsGiOuQ==$ZnaWnEOVWbKQTMdRi4AJ3KrDXeDps7BqKmUIOfXJVVw=

It consists of four parts, each delimited by the $ character:

• the name of the algorithm,
• the number of iterations used by the PBKDF2 algorithm,
• the salt
• and the hash.

Storing this information is useful in case the number of iterations becomes insufficient (due to increased computational capacity) or if the algorithm is deprecated in favor of more secure ones. In this case, an algorithm rotation can be performed.

When a user logs in, the application retrieves the algorithm and its arguments (the number of iterations in this case) from the database. If the algorithm and arguments are considered safe, they are used to hash the submitted password and test if it is valid as usual.

If the algorithm and arguments are not up to date, the framework performs an additional step. After the password is verified and approved, a new hash is generated with the latest security guidelines and replaces the one previously stored in the database. The algorithm information is also updated.

This way, it is ensured that as many passwords as possible in the database are hashed with the latest security recommandations.

Context

Integration testing can be tricky to setup because of all external services that can be involved. For example a database, a file storage in the cloud,… As a developer the cost of implementation can be so big that we won’t take the time to implement integration tests. But the benefits are, in my opinion, worth the price especially for applications that are not updated very often. For example, we will be able to upgrade NPM dependencies with a high level of confidence without having to manually test the application each time.

In this article we will focus, as an example, on two external services which are a MongoDB database and AWS S3. We will see the different ways of dealing with these services to be able to implement some integration tests. This is not a full tutorial but more a reflexion about this problematic.

Mock and in memory DB

One of the easiest solutions to solve the problem is to mock the external services that we rely on. This way we don’t have to deal with a complex setup to be able to run our integration tests.

• Mock API call to AWS S3

beforeEach(async() => {
  getAwsLinkStub = sinon.stub().resolves('STUB_URL');
  aws.getReadSignedUrlWithAws = getAwsLinkStub;
});

One of the drawbacks of this solution is that we rely on our own interpretation of the results from the external service. For example, if the API of AWS is changing, our tests won’t fail but it will not work at runtime because there is a change in the API response that we are not aware of. Also mocking the responses can be tedious and time consuming especially when we have a lot of them.

• MongoDB in memory

this.mongod = await MongoMemoryServer.create({
  instance: {
    dbName: 'myDb',
    storageEngine: 'ephemeralForTest',
  },
  binary: {
    version: mongoVersion,
  },
});

This is a good solution, even though there are some limitations on performances for example, but it should not be a problem in most cases. One of the drawbacks could be that this is not exactly the same database as what we have in production so the behaviour can be different between the two environments.

GitHub Actions Services

In GitHub Actions there is a concept of “services” which are like docker-compose services but not exactly the same. This allows us to “deploy” our services as we would have them in production. Then our code can run the same way as it does in production which is really handy to write integration tests.

Below you can find an example of configuration for GitHub Actions. There is an actual MongoDB container running and exposing port 27017 to be able to request, save and delete data from a database as we would do it in production. Also, we have a MinIO service which is an open source object storage solution that expose the same API as AWS S3.

jobs:
  ci:
    runs-on: ubuntu-latest
    services:
      mongodb:
        image: mongo:5.0.4
        ports:
          - 27017:27017
      minio:
        image: minio/minio:latest
        ports:
          - 9000:9000
        env:
          MINIO_ROOT_USER: MINIO_ROOT_USER
          MINIO_ROOT_PASSWORD: MINIO_ROOT_PASSWORD
          MINIO_ACCESS_KEY: MINIO_ACCESS_KEY
          MINIO_SECRET_KEY: MINIO_SECRET_KEY

This is a great solution to facilitate the writing of integration tests but one of the caveat is that we have to run the same container manually in local to be able to run the tests. So we will need a docker-compose file that exposes the same container that we will have in our CI.

The GitHub Actions also have some limitations: for example we can’t explicitly define the command to executed inside the container which can be annoying when the Dockerfile doesn’t set a CMD. Finally, this relies on the CI tool, which is GitHub Actions in our example, but not all companies use it…

TestContainers

As we have seen, the GitHub Actions services are a good solution to our problem but the main issue is that it relies on the fact that you are using GitHub which may not be the case. The good news is that if your test environnement supports Docker, you can benefit from the same kind of advantages as the GitHub Actions services but directly inside your code. At least this is the promise of TestContainers, a solution to help us, developers, to setup and write integration tests. From their website, TestContainers is described as:

Testcontainers is a Java library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.

The other good news is that it exists a version for NodeJS. The main advantage being that it’s a CI agnostic solution as long as you have access to the Docker daemon.

From a code standpoint it looks a bit like this:

describe('testContainer', () => {
  let mongoContainer: StartedTestContainer;
  let mongoClient;

  let minioContainer: StartedTestContainer;
  let minioClient;

  beforeAll(async () => {
    mongoContainer = await startMongoContainer();
    mongoClient = await getMongoClient({ container: mongoContainer });

    minioContainer = await startMinioContainer();
    minioClient = await getMinioClient({ container: minioContainer });
  });

  afterAll(async () => {
    await mongoContainer.stop();
    await minioContainer.stop();
  });
});

Basically you’re creating containers from your test code to be able to have access to your Mongo database and your Minio instance. Now let’s see in details how the container are created inside the startMongoContainer and startMinioContainer functions.

async function startMongoContainer() {
  const container = await new GenericContainer('mongo:4.2.6')
    .withExposedPorts({ container: 27017, host: 27018 })
    .start();

  return container;
}

async function startMinioContainer() {
  const container = await new GenericContainer('quay.io/minio/minio:RELEASE.2022-04-01T03-41-39Z')
    .withEnv('MINIO_ROOT_USER', 'indy')
    .withEnv('MINIO_ROOT_PASSWORD', 'indy/AWS_ACCESS_KEY/AWS_SECRET_ACCESS_KEY')
    .withEnv('MINIO_ACCESS_KEY', 'indy')
    .withEnv('MINIO_SECRET_KEY', 'indy/AWS_ACCESS_KEY/AWS_SECRET_ACCESS_KEY')
    .withExposedPorts({ container: 9000, host: 9999 })
    .withCmd(['server', '/data'])
    .start();

  return container;
}

As you can see it’s a simple way to create containers and to configure them directly in the code. We can easily specify the Docker image to use, provide environment variables, expose ports and execute a specific command to launch the container. Then we get the container instance that we can use to create our clients to consume the services. To see that let’s dive in the getMongoClient and getMinioClient functions.

async function getMongoClient({ container }: { container: StartedTestContainer }) {
  const mongoClient = await new MongoClient(
    `mongodb://${container.getHost()}:${container.getMappedPort(27017)}/${config.mongo.dbName}`,
  ).connect();

  return mongoClient;
}

async function getMinioClient({ container }: { container: StartedTestContainer }) {
  const minioClient = new Minio.Client({
    endPoint: container.getHost(),
    port: container.getMappedPort(9000),
    accessKey: config.aws.awsAccessKeyId,
    secretKey: config.aws.awsSecretAccessKey,
    useSSL: false,
  });

  return minioClient;
}

The container instance that we get from TestContainers is very convenient as it exposes various method to access the mappedPort, the host,… which is very useful to instantiate our clients.

Then we can easily run our tests using our containers and stop them at the end. We have the power of the containers directly inside our tests which can be very helpful in a context of integration testing. Another benefit is that you run your integration tests in the same environment in local and in the CI which is great for debug purposes.

I will end with 2 warning. Firstly be careful with the performances of your tests. Since we are creating containers it might take some time especially if we compare to the mock solution (but still less than asking to your ops team to create a DB for your tests). Secondly, the TestContainers for NodeJS is fairly new compare to the original Java version so all the functionalities may not be available yet and the overall stability of the project might be slightly below its counterpart.

Conclusion

What does TestContainers bring to the table ?

• A great balance between usability, speed and features.
• A CI agnostic tool that will encourage you to write more integration tests.
• The freedom of writing integration tests that relies on external services without having to wait for ops intervention.
• It frees you from making assumption when you mock external services responses in your integration tests.
• It allows you to run your integration tests in an environment as close as your CI and production environment.

What is the cost ?

• You need to have some kind of Docker running in your local machine, but it should be available no matter if you’re using Linux, MacOS or even Windows.
• You need to be able to start containers in your CI environment, which might involve some ops operations…

This is a project that exists for many languages (Java, JavaScript, Go, Rust,…) and that seems to be used by various companies (JetBrains, Spring, Wise,…). It’s quite easy to start and experiment with so I heavily encourage you to give it a try.

Resources

Main website: https://www.testcontainers.org/

TestContainers NodeJS: https://github.com/testcontainers/testcontainers-node

Interesting talk about integration tests and TestContainers: https://youtu.be/X2Qd4Myy-IY

Un article a déjà été écrit par Virgil Roger, où il parle de son ressenti du télétravail, ainsi vous pourrez comparer nos 2 manières d’appréhender cette façon de travailler 🙂. L’article est disponible ici.

Le full-remote n’est pas une pratique qui s’improvise, et il peut être vécu différemment selon chaque personne. Bien pratiqué, certains peuvent trouver une sérénité qu’ils n’ont pas sur site, et inversement, on peut s’enfermer sur soi-même très facilement.

Ici, je partage mon retour d’expérience et ma manière de pratiquer le télétravail au sein d’Indy.

Avant Indy

Comme beaucoup, j’ai connu le télétravail durant le premier confinement, j’étais en dernière année de Master en alternance et je fus un peu désemparé au début.

Se retrouver à deux, confinés dans 18m2 tout en travaillant, ce ne fut pas simple (spoiler alert, on a réussi à ne pas s’entretuer 😛). J’ai dû réapprendre à travailler différemment, être loin de mes collègues.

Mais avec le temps, j’ai appris à aimer travailler de cette manière et je ne pourrais plus m’en passer. Et depuis, cela va faire 2 ans que je travaille (presque) depuis chez moi.

J’ai néanmoins essayé de retravailler sur site suite à un changement de travail, mais les open spaces bruyants, la perte de temps dans les transports, la fatigue en plus font que je ne suis pas resté.

Ma rencontre avec Indy

Me voilà en mars 2022, chez Indy pour un poste en full remote. C’était une aubaine, pile ce que je cherchais ! Et qui alliait également bonne ambiance, bienveillance, la recette parfaite pour travailler dans de bonnes conditions.

Après avoir passé tous les entretiens, je suis admis au sein de cette entreprise. J’ai dû demander au moins 5 fois, à 5 personnes différentes si j’allais bien être en full remote (le trajet Grenoble/Lyon n’allait pas être une partie de plaisir tous les jours) et j’ai toujours eu des réponses positives.

Moi, anxieux ? Absolument pas 🤫.

Avant mon arrivée, j’ai le choix entre un PC ou un Mac, ainsi que mes accessoires/périphériques (clavier, souris, …). Je demande aussi à avoir un écran chez moi, qu’on m’octroie sans soucis (spoiler alert, il m’a été directement livré chez moi suite à ma semaine d’intégration 🤤).

Mes débuts

Première semaine d’onboarding.

J’avais le choix de faire cette semaine en présentiel ou en remote. J’ai opté pour le présentiel, qui pour moi était synonyme de meilleure intégration et faciliterait les rencontres avec mes futurs collègues. Le voyage ainsi que le logement étaient pris en charge par l’entreprise (un des avantages quand on est en full remote à Indy !).

Et c’est ainsi que le lundi 7 mars, 8h15, j’arrive pour la première fois à Lyon Part Dieu avec mon sac pour une semaine. Pour faire simple, durant une semaine, on assiste à une dizaine d’ateliers avec différentes personnes de l’entreprise afin de nous expliquer le fonctionnement d’Indy, les différents pôles, un petit cours de comptabilité (c’est toujours mieux de savoir de quoi on parle), etc. Avec une soirée d’intégration en mon honneur jeudi soir, et nous voila déjà vendredi, jour où je dois repartir.

Et je dois dire qu’à ce moment-là, je suis partagé entre vouloir rester et être content de rentrer chez moi, pour retrouver mon bureau et tout le reste. Les open spaces étaient “bizarrement” calmes, des phonebooths sont à disposition un peu partout afin de s’isoler pour téléphoner, tous les collaborateurs sont bienveillants et prêts à aider si besoin, les bureaux sont spacieux et bien équipés, ce qui a fait que je n’ai pas vu passer cette semaine.

Voilà donc ma deuxième semaine de travail, en full remote cette fois-ci.

Le full-remote à Indy

Embaucher des personnes en full remote est une première à Indy, je suis d’ailleurs le seul, mais ce n’est pas pour autant que je me sens isolé ou livré à moi-même.

Il y a tout de même quelques exceptions, deux collègues présents depuis la création d’Indy à Paris sont en télétravail suite au déménagement de l’entreprise à Lyon.

Indy utilise beaucoup le télétravail, il y a une alternance imposée pour les salariés qui ne sont pas en full remote qui correspond à 2 jours par semaine sur site minimum. Pour ma part, je dois venir entre 2 et 3 jours par mois.

De ce fait, tous les employés sont déjà habitués à travailler à distance ou avec des collègues qui le sont. On utilise des outils pour faciliter le lien et les échanges comme Google Meet, Around, Metro Retro ou encore Slack. La seule différence entre mon équipe et moi, c’est le nombre de jours de présence à Indy.

Nous avons convenu qu’à chaque fois que je décide de venir, je préviens mon équipe en avance afin de prévoir des moments de convivialité avec un restau par exemple.

Les clefs du succès

À vrai dire, je sais que le full remote n’est pas fait pour tout le monde. Il est très compliqué pour certains de travailler “seul” dans son coin chez soi, et c’est tout à fait normal.

Pour ma part, ce qui a fonctionné, et qui fonctionne encore, ce sont plusieurs choses.

Une entreprise adaptée au télétravail

Indy prône l’asynchrone. Il est possible de travailler un peu comme on le souhaite tant qu’on prévient notre équipe et qu’on respecte certaines règles :

• Prévenir notre équipe lorsqu’on s’absente.
• Tenir à jour notre Google Calendar pour indiquer les jours où on est sur site, les absences dans la journée, etc.
• Toutes les informations doivent passer par Slack ou Notion, que ça soit des questions, des partages d’article de dev, ou autre. Ainsi, cela nous permet d’avoir de grosses bases de données nous permettant de rechercher tous types d’informations (ce qui est pratique au quotidien, quand un sujet a déjà était traité et qu’on cherche une réponse).

Ne pas être seul

Ma femme étant aussi 3 jours par semaine en télétravail, je suis rarement seul toute une journée. Travaillant à deux à la maison, c’est comme si j’étais avec une collègue qui ne travaillait pas dans le même service. On prend nos pauses ensemble, on échange sur nos travails respectifs, et on retourne travailler. On évite de déranger l’autre un maximum. Bizarrement, une limite s’est créée la journée entre nous deux, on devient “collègues” jusqu’à 17h, où là on se retrouve en tant que couple. Et c’est ce qui nous a permis de tenir durant les confinements et le full remote depuis 2 ans.

Ne pas être le seul en télétravail

Mon équipe au sein d’Indy pratiquait aussi énormément le télétravail avant mon arrivée, donc elle avait des process avancés permettant cela. On échange beaucoup via Slack et Around, et on pratique énormément de pair programming à distance (je ne travaille pas une seule journée sans faire du pair ou échanger avec quelqu’un de mon équipe). Enfin, on a aussi des 1-1 avec le PM de l’équipe et mon manager toutes les semaines, ce qui permet de garder un contact avec certains membres avec qui on n’échange pas tous les jours.

L’équipement chez soi

C’est primordial ! Avoir un bon bureau, une bonne chaise de bureau (coucou Herman Miller 👋), une bonne connexion internet (merci la fibre 🙏), un ou plusieurs écrans. De plus, il faut aussi avoir un endroit isolé comme une pièce bureau ou du moins un coin travail qui nous permet d’être dans notre bulle.

Sortir !

En full remote, il est facile de rester une semaine chez soi sans sortir. Donc, il faut s’obliger à sortir, que ça soit boire un coup, aller à la salle de sport, des randos ou autre. Sinon le métro/boulot/dodo devient juste boulot/dodo sans interactions sociales.

Les limites du full remote

Hormis le fait d’être bien intégré dans son équipe, des fois, on peut se sentir exclu.

Indy prévoit énormément d’activités/événements au quotidien et il est impossible d’y participer à distance. Par exemple, il y a eu un bar à céréales, un atelier gaufre, une chasse aux œufs de pâques pour les enfants des employés, un atelier dégustation de thé glacé, un meetup JavaScript, etc.

Cela induit forcément une notion de choix, j’organise mes déplacements en fonction des activités qui m’intéressent comme la soirée de fin de clôture des déclarations pour les entreprises (très attendue chez Indy, ça annonce la fin du rush !), les team buildings, ou encore les soirées organisées par le BDE (comme à la fac, mais ici c’est le Bureau Des Employés).

Même si certains ateliers ne m’intéressent pas, j’aurais bien aimé partager avec ceux qui l’ont fait durant une pause. On loupe aussi des discussions informelles autour de la machine à café, qui permettent d’échanger des banalités avec tout le monde.

Mais pour ce dernier point, Indy a trouvé la parade : les “Donuts”. Ce sont des petits moments à prendre à distance ou en présentiel avec quelqu’un de l’entreprise, au hasard, juste pour pouvoir échanger de tout et de rien. Même si c’est plus sympa de les faire en présentiel, ça permet de garder un lien et apprendre à connaitre de nouvelles personnes.

Enfin, comme je l’ai dit, il est très facile de se renfermer sur soi-même si on ne fait que travailler seul. Pour moi, c’est le plus gros défaut du full remote.

Conclusion

Contrairement aux globe-trotteurs qui télétravaillent en voyageant aux 4 coins du monde, si j’ai choisi le télétravail, c’est principalement pour faciliter l’équilibre vie personnelle et professionnelle.

À Indy, tous mes collègues sont compréhensifs sur ma situation particulière, je ne me sens donc pas isolé. Même si des fois j’aimerais venir plus souvent pour partager des activités avec tout le monde, ce n’est pas un choix que je regrette. Vivant excentré de la ville, je perdrais en qualité de vie, et je ne pense pas être prêt à revenir sur site tous les jours.

Bien sûr, le full remote peut être compliqué à mettre en place, et il faut être pleinement conscient des bons et des mauvais côtés, que ça soit mentalement ou autre.

Et vous alors ? Êtes-vous prêt à franchir le pas ?

Vous vous souvenez de cet article (en anglais) ? J’y abordais le sujet de l’accessibilité et de l’utilisation d’une application web par une personne en situation de handicap.

Et bien ça n’aura pas loupé, à peine l’article publié notre Delphine préférée (office manager de son état) a communiqué en internet sur l’avancement des différents projets d’inclusivité chez Indy.

Occasion rêvée d’adresser la problématique concrètement dans la vraie vie (l’IRL quoi). Et vous savez quoi ? C’est plus dur que ça en a l’air ! Donc autant partager les découvertes, non ?

C’est donc parti pour un journal de bord du projet d’amélioration des problématiques d’accessibilité de l’application Indy et de ses copines utilisées en interne.

---

🐣 JOUR 1 : naissance de #dev_guilde-accessibility

En dessous du message ci-dessus (vous suivez ?), j’en ai gentiment appelé à l’équipe produit Indy pour savoir si des projets étaient déjà en cours sur le sujet.

→ non, pas formellement du moins, même si nous y sommes tou·te·s sensibles et attentifs.

Qu’à cela ne tienne, maintenant c’est le cas. Et “ownership” oblige, je vais le mener.

Plus on est de neurodivergents plus on rit ? Eloïse et Benjamin se proposent instantanément pour me filer un coup de main. Et comme il n’y a pas que le javascript dans la vie (et dans le produit), c’est Léa qui va venir représenter le customer care, et donc nos clients.

Tout ça, ça crée une guilde des plus sympathiques !

---

🏁 JOUR 2 : c’est partiiiii

Mercredi 13 juillet, première réunion. Où l’on se réunit pour savoir où l’on veut aller.

Objectif du jour : entériner la création de la guilde accessibilité produit, son périmètre, sa raison d’être, ses missions et des objectifs actionnables.

En effet, l’accessibilité n’est pas une tâche atomique, et il faut savoir définir des objectifs considérés suffisants car on aurait trop vite fait de poursuivre son amélioration à l’infini.

Et comment savoir si on est allé trop loin ? Il faut savoir si et quand on a fini, et donc pouvoir mesurer un niveau de “qualité” des applications à atteindre et maintenir.

Et comment savoir si on est allé assez loin ? Il faut déjà savoir d’où l’on vient, et donc pouvoir mesurer le niveau actuel de l’accessibilité des applications. Donc faire un audit de l’existant.

---

🛠️ JOUR 3 : les premiers coups dans la fourmilière

On n’est pas venus pour souffrir, OK ? Alors on ne va pas réinventer le fil à couper l’eau tiède, il y en a déjà de très bien dans le commerce.

Par contre on va très sérieusement appliquer les recommandations de l’état de l’Art sur le sujet.

Mais un pas après l’autre, alors la première chose qu’on a faite, c’est ajouter cette ligne :

// .eslintrc.js
extends: ['plugin:vuejs-accessibility/recommended'],

Parce que oui, on fait du VueJS, on utilise ESLint, et on travaille sur l’accessibilité.

Donc on a ajouté le plugin ESLint VueJS-Accessibility. Logique imparable !

Et le recommended alors ?

Il correspond à :

rules: {
    "vuejs-accessibility/alt-text": "error",
    "vuejs-accessibility/anchor-has-content": "error",
    "vuejs-accessibility/aria-props": "error",
    "vuejs-accessibility/aria-role": "error",
    "vuejs-accessibility/aria-unsupported-elements": "error",
    "vuejs-accessibility/click-events-have-key-events": "error",
    "vuejs-accessibility/form-control-has-label": "error",
    "vuejs-accessibility/heading-has-content": "error",
    "vuejs-accessibility/iframe-has-title": "error",
    "vuejs-accessibility/interactive-supports-focus": "error",
    "vuejs-accessibility/label-has-for": "error",
    "vuejs-accessibility/media-has-caption": "error",
    "vuejs-accessibility/mouse-events-have-key-events": "error",
    "vuejs-accessibility/no-access-key": "error",
    "vuejs-accessibility/no-autofocus": "error",
    "vuejs-accessibility/no-distracting-elements": "error",
    "vuejs-accessibility/no-onchange": "error",
    "vuejs-accessibility/no-redundant-roles": "error",
    "vuejs-accessibility/role-has-required-aria-props": "error",
    "vuejs-accessibility/tabindex-no-positive": "error"
  }

Après on a npm run lint et notre terminal s’est mis à clignoter de toutes les couleurs (enfin, tant que c’est du rouge).

Après on a retroussé nos claviers, et on a réparé toutes les erreurs remontées par le plugin :

Avec sur le podium des choses pas top :

1. vuejs-accessibility/label-has-for
2. vuejs-accessibility/click-events-have-key-events
3. vuejs-accessibility/form-control-has-label

Et pour une utilisatrice malvoyante, ça aurait posé souci dans les formulaires !

Après on a regardé notre code, tout ce qu’on avait amélioré “et voici, cela était très bon”. Enfin, un peu mieux quoi. C’est pas fini !

Et sans grande difficulté qui plus est, comme quoi parfois c’est pas compliqué de bien faire :

---

🚀 DEMAIN : la suite au prochain épisode

Non, c’est pas fini, loin de là. Ce premier article touche à sa fin car le jour 3 s’est achevé hier.

Mais demain ? Demain on va continuer !

Parce que c’est bien beau de regarder les recommandations, mais ça ne répond pas nécessairement aux besoins de nos utilisateurs. Et nos utilisateurs c’est notre raison de travailler.

Donc à prévoir :

• Des sondages auprès de nos utilisateurs (internes et externes) pour déterminer les priorités
• Des audits plus poussés (tout ne peut pas se voir dans le code, exemple tout bête : le contraste d’un texte ou les couleurs d’un bouton)
• La détermination d’indicateurs fiables pour suivre l’évolution de l’accessibilité
• La rédaction d’une convention technique pour encadrer le développement de nos applications et intégrer l’accessibilité aux bonnes pratiques de code chez Indy
• Un deuxième article de blog !

Introduction des événements métiers chez Indy

Tag : scalabilité, architecture

Authors : Koenig R. avec l’aide de la team Core

Termes employés

Qu’entendons-nous par événement métier chez Indy ? Dans le cadre d’Indy et de sa comptabilité je vais donner des exemples qui peuvent vous parler, histoire de bien illustrer la chose :

Nous aurons un événement métier lorsque par exemple un utilisateur…

• termine son onboarding
• s’abonne
• ajoute son compte bancaire
• clôture sa liasse fiscale
• ajoute une transaction
• change la catégorie d’une transaction

etc…

Lorsque ces événements arrivent, on veut pouvoir exécuter du code qui n’est pas relatif au cœur du produit. J’entends par là, par exemple, que lorsqu’un utilisateur ajoute une transaction, on exécute bien le code métier qui ajoute une transaction dans l’application : C’est le produit. Mais on veut aussi exécuter du code qui n’a rien à voir avec ce cœur de produit et ça peut être assez divers : Envoyer un email ou une notification, mettre à jour un CRM, envoyer une requête à un microservice.

Ce code lui est nécessaire au bon fonctionnement de l’entreprise, mais le produit et l’utilisateur, eux, s’en fichent. Ainsi il serait dommage que l’utilisateur final soit pénalisé par du code destiné aux équipes d’Indy. Que ce soit en termes d’erreur, bugs ou de délais à cause d’un élément exogène.

Exemples de problèmes “Avant”

Pour illustrer un peu plus loin les problèmes qui ont pu nous mener à cette réflexion, je propose de voir des exemples sur lesquels nous nous sommes cassés un peu les dents :

Exemples :

import serviceX from 'serviceX';
import serviceY from 'serviceY';
import CRM1 from 'CRM1';

function finalizeOnboarding(...) {
	const user = await saveUser(); // do the interesting stuff for the client
	await serviceX.initConfigurationServiceX();
	await serviceY.initConfigurationServiceY();
	// [...]
	await serviceX.updateCRM1(); // That is our stuff
	return user;
	}

Les trois dernières fonctions sont indépendantes, mais elles doivent être exécutées lors de la finalisation de l’onboarding.

Le premier problème est qu’une erreur dans une de ces fonctions peut entraîner la non exécution des suivantes, qui pourtant ne sont pas liées (elles n’attendent pas le retour des précédentes) et laisser le code et la data dans un état incertain. Dans le pire des cas : On renvoie même une erreur à l’utilisateur qui est bloqué dans son onboarding.

Alors on peut répondre à ce problème en ajoutant des try catch et c’est ce que nous avons fait :

import serviceX from 'serviceX';
import serviceY from 'serviceY';
import CRM1 from 'CRM1';

function finalizeOnboarding(...) {
	const businessResult = await myBusinessFunction();
	try {
		await initConfigurationServiceX();
	} catch (error) {
		// do something... maybe
	}
	try {
		await initConfigurationServiceY();
	} catch (error) {
		// do something... maybe
	}
	try {
		await updateCRM1();
	} catch (error) {
		// do something... maybe it depends of the CRM
	}
	return businessResult;
}

C’était un compromis simple et rapide, qui nous a permis de continuer un certains temps.

Ici nous n’avons plus le problème des erreurs mais nous avons encore des fonctions qui sont liées de manière synchrone. Typiquement si une fonction prend beaucoup de temps, elle va différer l’exécution des suivantes, ainsi que l’exécution de la fonction finalizeOnboarding de manière générale.

On pourrait éventuellement répondre à ce point en les wrappant aussi d’un setImmediate. Ce que nous verrons dans la suite. (aussi possible de faire sans await avec un simple .catch)

En monitoring, cette fonction nous a montré qu’elle pouvait s’exécuter en 0.2s comme parfois 4s et même plus rarement 40s, en fonction du temps de réponses des API externes… Car souvent nos outils sont des SaaS externes ! Ce qui bien sûr peut entraîner un timeout pour le client. Ces événements devenant plus fréquents, cette implémentation est de moins en moins acceptable. (problème :performances)

Un autre problème est la charge mentale. Un autre développeur, s’il ne connaît pas l’historique, ou s’il l’a oublié, peut assumer que ces fonctions ne sont pas indépendantes et que l’ordre doit être respecté : Par exemple parce que chaque fonction va muter l’état en base de données et que les autres s’attendent à ce nouvel état (ce qui est une mauvaise pratique, mais comment savoir quand on ne connaît pas le code par cœur ?). Sans une inspection de chaque fonction c’est difficile de savoir, la confiance s’en trouve réduite, et ça freine le développeur dans sa refonte éventuelle, dans son ajout de feature etc… ( problèmes: perte de confiance, pauvre maintenabilité)

Je continue dans ma liste des problèmes : A un autre endroit de l’application nous avions des fonctions à exécuter lors d’une modification sur un modèle, c’était fait via un hook :

import updateCRM from './crm.service.js';

async function postHook(user) {
	try {
		await updateCRM(user);
	} catch(err) {
		logError(err)
	}
}

Cette fonction étant dépendante du service de CRM en question qui est un service de haut niveau et qui importe d’autres modules.

Ce qui a pour effet de coupler notre modèle de données à d’autres modèles et services d’autres modules, CRM1 dépendant de tous.

Ce qui entraîne des problèmes d’imports, des dépendances circulaires, des difficultés à comprendre et étendre le système.

(problèmes: couplages des services, violation d'architecture)

Solution

On veut pouvoir : Exécuter du code sans bloquer la requête initiale

Bien sûr le code métier qui doit être fait par la route et nécessaire à la réponse faite au client sera bloquant, mais le code indépendant qui doit être exécuté ne doit plus l’être pour la requête initiale, comme la mise à jour d’un CRM par exemple.

Alors pour répondre au problème du non bloquant nous pouvons utiliser setImmediate:

import serviceX from './serviceX';
import serviceY from './serviceY';
import CRM1 from './CRM1';

function finalizeOnboarding(...) {
	const businessResult = await myBusinessFunction();
	setImmediate(() =>
		try {
			await serviceX.initConfigurationServiceX();
		} catch (error) {
			// do something... maybe it depends of the CRM
		}
	));
	setImmediate(() =>
		try {
			await serviceY.initConfigurationServiceY();
		} catch (error) {
			// do something... maybe
		}
	));
	setImmediate(() =>
		try {
			await serviceX.updateCRM1();
		} catch (error) {
			// do something... maybe
		}
	));
	return businessResult;
}

et

import updateIntercom from 'intercom.service.js';

async function postHook(user) {
	setImmediate(() =>
		try {
			await updateIntercom(user);
		} catch(err) {
			LogError(err)
		}
	));
}

Cela peut résoudre le premier point (Toujours est-il que la lecture de la fonction ne s’améliore pas).

Mais nous avons toujours le problème des dépendances. Pour ça, on va vouloir :

⇒ Casser la dépendance et découpler notre code applicatif du code qui doit réagir. (Inversion of control)

Par exemple, on ne veut plus que le model user dépende du service Intercom qui est un CRM. Cela parait évident mais je me permets d’enfoncer le clou avec le OCP (Open Closed Principle) de SOLID comme quoi le code doit être ouvert à l’extension et fermé à la modification.

Typiquement si demain on ajoute un nouveau CRM, ou un nouveau module métier je ne veux pas avoir à modifier le code de User pour y insérer : “Importer le code du nouveau module, appeler la bonne fonction pour l’action désirée comme mettre à jour le CRM ou initialiser le module”.

Mais on doit pouvoir ajouter un nouveau service, qui aura une fonction qu’il faut appeler, au bon moment, qui ne bloquera pas la fonction métier originelle, qui pourra être monitorée par ailleurs pour ceux que ça regarde sans polluer ceux qui s’occupent du métier. Le tout étant dans un fichier/dossier/repo différent qui peut être la responsabilité d’une autre équipe.

Pour avoir l’inversion of control il nous faut le pattern Observer.

Observer Pattern

(voir section JavaScript pour la suite)

class Subject {
	observers = [];
	attach(observer) {
		this.observers.push(observer);
	}
	notify() {
		this.observers.forEach((observer) => {
			observer.update();
		})
	}
}

class Observer {
	update() {
		// Do what you have to do
	}
}

Par exemple, car c’est plus clair avec des exemples, nous aurons ici User qui serait un subject et les différents modules et/ou CRM des observers.

Comme Intercom observe le user et réagit à ses changements d’état, nous avons l’observer qui importe le Subjet pour avoir accès à la fonction attach et s’attache.

Le rôle du sujet est juste de signaler son changement d’état via notify et la fonction update de l’Observer sera appelé :

// intercom.service.js
import User from './user';

class intercom {
	async update() {
		// Build data and call API
	}
}

User.attach(intercom);

Et dans User nous avons désormais :

async function postHook(user) {
	setImmediate(() =>
		try {
			this.notify();
		} catch(err) {
			LogError(err)
		}
	));
}

L’import a disparu du fichier User ! 🎉 Nous avons donc un fichier haut niveau qui importe un fichier plus bas niveau (User ici) tout est rentré dans l’ordre.

Bon dans cette implémentation naïve, tout est synchrone, la gestion des erreurs n’est pas faite, on veut pouvoir avoir des noms d’événements différents pour un même sujet… Il reste du chemin à faire.

Heureusement la plupart des langages offrent de manière native des class pour implémenter ce pattern et en Node nous avons EventEmitter.

https://nodejs.org/api/events.html

Pourquoi tant de focus sur ce découplage ?

En tant qu’architecte chez Indy, un de mes principaux driver aujourd’hui est de gérer une base de code modifiable par une équipe de plus de 30 développeurs, et de poser les fondations pour une équipe de 60 développeurs.

D’expérience, les problèmes de communications priment sur les problèmes techniques pour lesquels on trouve toujours une solution. C’est pourquoi découpler le code, et par extension les teams qui en sont responsables est un objectif très haut dans ma roadmap.

Typiquement, sur le code vu plus haut, la gestion du modèle user pourra être l’object d’une squad A, pendant que la gestion du CRM1 pourra être la responsabilité d’une squad B etc…

Le code pouvant être protégé par le système de code owners (de Github ou GitLab), et les squads pouvant avoir des priorités différentes, je veux que chacune puisse avancer au maximum sans attendre le retour d’une autre.

C’est pourquoi ce découplage est si important à mes yeux.

Avec ce pattern, on peut avoir un code métier complètement découplé du code non-métier destiné à l’entreprise. De plus on peut avoir autant de listeners que l’on veut, ces derniers étant découplés entre eux aussi.

L’enjeu ici, c’est définir les interfaces entre les squads et comment je les sépare. Ici je réponds au fait que ce sont les Services externes qui importent User et qui réagissent dessus. Le code entre les squads est soumis aux ADRs (ensemble de règles et conventions que nous avons entre développeurs chez Indy) ce qui ne sera pas forcément le cas du code soumis à une seule squad.

Implémentation moins naïve

import EventEmitter from 'events';
import _ from 'lodash';
import { createLogger, newEventContext } from '../../logger.js';
import config from '../../config';
import { getCheckAlreadyRegisteredListener, isEventListenerEnabled } from './applicationEvents.model';

const logger = createLogger({ namespace: 'application-events' });
const eventsEnabledConfig = config.private.applicationEvents.events;
const listenersEnabledConfig = config.private.applicationEvents.listeners;
const eventListenersEnabledConfig = config.private.applicationEvents.eventListenerPairs;

export function createApplicationEvents() {
	const eventEmitter = new EventEmitter();
	eventEmitter.setMaxListeners(10);
	eventEmitter.on('error', (err) => {
		logger.error({ err }, '[ApplicationEvents] Internal event emitter error');
	});
	// Memoize to prevent log spam
	const logEventWithoutListener = _.memoize(({ eventName }) => {
		logger.info(
			{ eventName },
			'[ApplicationEvents] An event has been emited but no listeners are registered for this event',
		);
	});

	return {
		emit(eventName, payload) {
			// Don’t trigger the event if it is disabled
			if (!isEventListenerEnabled({ name: eventName, config: eventsEnabledConfig })) return;
			const listenerCount = eventEmitter.listenerCount(eventName);
			if (listenerCount === 0) {
				logEventWithoutListener({ eventName });
			}
			return eventEmitter.emit(eventName, payload);
		},
		on(eventName, listenerName, cb) {
			const eventListenerKey = `${eventName}-${listenerName}`;
			// Don’t register the event if the listener is disabled
			if (!isEventListenerEnabled({ name: listenerName, config: listenersEnabledConfig })) return;
			// Don’t register the event if the pair event-listenner is disabled
			if (!isEventListenerEnabled({ name: eventListenerKey, config: eventListenersEnabledConfig })) return;
			checkAlreadyRegisteredListener({ eventListenerKey });
			eventEmitter.on(eventName, async (payload) => {
				setImmediate(() => newEventContext({ eventName: eventListenerKey }, () => cb(payload, eventName)));
			});
		},
	};
}

Quel type de payload dans les événements métiers ?

⇒ Payload minimal

Lorsqu’on émet un événement, on peut passer plus ou moins de data à cet évènement pour les listeners derrières.

Payload léger

Il s’agit de passer le minimum syndical d’informations pour que les listeners puissent fonctionner, ce qui a pour but d’alléger au maximum la fonction métier, typiquement on passe des arguments non objets, type String ou Number comme un ID :

async function updateUser({ userId, newFields }) {
	await UserRepository.udpate({ userId, newFields }});
	User.emit('updateUser', userId);
}

// Other file :
User.on('updateUser', (userId) => {
	const user = UserRepository.findOne({ userId });
	await updateCRM1(user);
})

// Other file :
User.on('updateUser', (userId) => {
	const user = UserRepository.findOne({ userId });
	await updateCRM2(user);
})

On pourra essayer de DRY (Don’t repeat yourself) par la suite, mais sans compromettre le driver numéro 1 de découplage.

Payload lourd

Une autre approche est de préparer le payload pour les listeners, ce qui peut éviter de recopier du code, d’alléger les appels à la base de données :

async function updateUser({ userId, newFields }) {
	await userRepository.udpate({ userId, newFields }});
	const user = userRepository.findOne({ userId });
	userEvents.emit('updateUser', user);
}

// Other file :
userEvents.on('updateUser', (user) => {
	await updateCRM1(user);
})

// Other file :
userEvents.on('updateUser', (user) => {
	await updateCRM2(user);
})

Ici on introduit donc une fonction non nécessaire au métier dans la première fonction updateUser, le contrat entre l’évènement et ces listeners est plus fort. Donc la première team doit avoir une meilleure connaissance des listeners potentiellement gérés par d’autres personnes.

Le compromis ici est une interface et une contrainte plus forte entre les teams composées d’humains pour une optimisation du code.

Conclusion

Il se trouve que la plupart du temps l’optimisation de code de la solution 2 est négligeable comparé au coût de communication humain, et c’est pourquoi ce n’est pas notre priorité et que cette solution n’est retenue que dans les cas prouvés comme étant problématiques.

Les deux peuvent fonctionner, mais étant donné que notre driver architectural est le découplage. Nous allons retenir la solution 1 du payload léger, quitte à gérer les côtés négatifs dans un second temps.

On utilise un pattern Observer basé sur le EventEmitter de Node pour découpler le code et les teams aux maximum. En ce qui concerne les évènements, le payload sera minimal et les listeners seront aussi découpés dans des fichiers différents.

Dependency Injection (DI) is a technique in which a software component receives other components (its dependencies) without it to have the responsibility to resolve and instantiate them.

This can favour loose coupling between the components, and separation of concerns: the client has only to manage its own functionalities.

Introduction example

Consider the following pseudo code:

// bankAccount.service.js
import { createConnectionPool } from './db.js'
import { createUsersService } from './user.js'
import { createAuthorizationService } from './authorization.js'

export const createBankAccountService = ({conf}) => {
    const db = createConnectionPool({conf});
    const Users = createUsersService({db});
    const Authorization = createAuthorizationService({Users});
    
    return {
        async createBankAccount({userId, bankAccount}) {
            const authorization = Authorization.authorizeBankAccount({userId});
            if (!authorization) {
                throw new Error('can not authorize bank account');
            }
            return db.query(createBankAccountQuery({bankAccount}));
        }
    };
};

You’ll note that the bank account service:

• Has to create its dependencies, which may imply creating transitive dependencies: ie the dependencies of its own dependencies. In particular, the bank account service creates a user service it will not use by itself.
• Has to import the factories of its dependencies (the functions used to create those services). It means the bank account service needs to know where to find these factories. As a side effect, the bank account service is coupled to specific implementations of its dependencies rather than using abstract interfaces.
• Although not a big problem, this instanciation code also clutters the service logic.

In comparison, consider the following snippet:

export const createBankAccountService = ({Authorization, db}) => {    
    return {
        async createBankAccount({userId, bankAccount}) {
            const authorization = Authorization.authorizeBankAccount({userId});
            if (!authorization) {
                throw new Error('can not authorize bank account');
            }
            return db.query(createBankAccountQuery({bankAccount}));
        }
    };
};

The bank account service does not create any dependency but got them injected, with the following direct benefits:

• The transitive dependency Users has disappeared
• The service does not depend on any specific implementation of Authorization and db as long as what get injected implement the same interfaces
• The code is less cluttered and more readable
• The service itself focuses on its own functionalities and nothing else.

The Injector

Obviously, the code related to the resolution and instantiation of the various dependencies still exists somewhere, but in a component dedicated to that purpose. Let’s build this component: the injector.

import {createConnectionPool} from '../db.js';
import {createUsersService} from '../users.js'

// etc

const injectablesManifest = {
  db:createConnectionPool,
	Users: createUsersService
};

const injectables = inject(injectablesManifest);

The inject function should be able to resolve the whole dependency tree based on the injectables manifest specifications: if Users depends on db, then const { Users } = inject(injectablesManifest) should give you an instance of Users with its dependencies resolved.

The manifest

The manifest (or registry) here is a sort of map whose keys are the injectables tokens (the values you will use to lookup for any particular injectable), and whose values are factory functions (functions used to create an instance of the injectable). These factories all have the same signature (Where deps is a map of any injectable):

const factory = (deps) => injectable

By using factory functions we can implement pretty much any instanciation pattern:

• If we always want the same instance of a given injectable (singleton), we can just wrap the factory into some sort of memoize function:

const factoryA = (deps) => {
		return {
			methodA() {},
			methodB() {}
		}
}

const memoize = (fn) => {
		let value;
		return (deps) => {
				if(value){
						return value;
				}

				return value = fn(deps);
		}
}

const getMySingletonA = memoize(factoryA)

// which complies with
import {test} from 'zora';

test('should always return the same instance of the injectable', (t)=>{
		t.ok(getMySingletonA() === getMySingletonA())
});

• If we have a constructor based instantiation (with classes), we only need to wrap the constructor into a function

class ServiceA {
		constructor(deps){

		}
}

const serviceAFactory = (deps) => new ServiceA(deps)

• value function: wraps any constant value into a function

const myDep = 'foo'; 

const valueFn = (val) => (whatever) => val

const myDepFactory = valueFn(myDep);

// wich complies with
import {test} from 'zora';

test('should return the constant', (t)=>{
		t.eq(myDepFactory(), 'foo')
});

This gives more flexibility over a class system with constructor based instantiation as you can see in many popular frameworks nowadays.

How you build or register the injectables factories into the manifest is out of the scope of this article and will depend on the context (going from a plugin system to a set of sophisticated class annotations, etc)

Solving the transitive dependencies problem with meta programming

As mentioned in the introduction: if you want a service A, but it depends on a service B which in turn depends on a service C, it is difficult to build all the services in the dependency chain. Based on the manifest (a flat structure), we can solve the problem of dependency resolution through meta-programming.

Considering that there is no circular dependency, you can model the relationships between the services with a Directed Acyclic Graph (DAG) where the nodes are the services and the vertices represent the “depends on” relationship.

We can leverage property descriptors to build a magic object which evaluates lazily the service factories as they are required based on the manifest.

Assuming the following small helper which maps the values of an object to a set of other values

const mapValues = (mapFn) => (object) => Object.fromEntries(
	Object
		.entries(object)
		.map(([prop, value])=> [prop, mapFn(value)])
)

// ex
const upperCase = mapValues(value=>value.toUpperCase());

upperCase({ foo: 'bar' });
> // { foo: 'BAR' }

We can build the property descriptors of our magic object

export const inject = (injectablesFactoryMap) => {
    const injectables = {}; // (1) the object which will hold the injectables
    const propertyDescriptors = mapValues(createPropertyDescriptor);

    // (2) we make this object a meta object which will instantiate an injectable whenever a token will be looked up
    Object.defineProperties(
        injectables,
        propertyDescriptors({
            ...injectablesFactoryMap
        })
    );
    
    return injectables;
    
    function createPropertyDescriptor(factory) {
        return {
            get() {
                return factory(injectables); // "injectables" are injected in every factory so the dependency graph is magically resolved
            },
            enumerable: true
        };
    }
};

1. We need first to create an empty object which will hold the injectables and will get in every factory when the latter is called.
2. This meta object keys are the injectables’ tokens and the property getters are overwritten in such a way that when you look up for a specific injectable (calling the getter), the factory is called. Interestingly as the factories themselves use the injectables object they receive, the relevant getters are called as well so that the whole graph is lazily resolved for the factory initially called.

This solves few of the problems:

• We automatically resolve the transitive dependencies.
• You only import the various factories once, when you build the manifest, making all the components agnostic of where their dependencies live

import { test } from 'zora';
import { inject } from './di.js';

// depends on "B"
const createServiceA = ({ B }) => {
  return {
    foo() {
      return B.foo();
    },
  };
};

// depends on "C"
const createServiceB = ({ C }) => {
  return {
    foo() {
      return C.foo();
    },
  };
};
const createServiceC = () => {
  return {
    foo() {
      return 'bar';
    },
  };
};

// injectable manifest: map a token to a factory
const manifest = {
  A: createServiceA,
  B: createServiceB,
  C: createServiceC,
};

test(`resolve transitive dependencies`, (t) => {
  const { A } = inject(manifest); // (1) here we call the getter for A
  t.eq(A.foo(), 'bar');
});

The statement (1) creates the dependency graph: when you destructure the meta-object, the getter of A is called, which leads to a cascade of calls to the getter of B, then to that of C.

💡 Note we can change the implementation of the mapValues function to also map properties whose key is a Symbol. This type of properties can operate as “secret tokens” to make some injectables only injectable to whomever knows or has access to the Symbol: you can’t lookup for a property whose key is a Symbol if you don’t have a reference of that Symbol.

test(`Use symbol for tokens`, (t) => {
  const sym = Symbol('foo');
  const manifest = {
    [sym]: valueFn('foo'),
    canAccessSymbol: ({ [sym]: foo }) => foo,
    cantAccessSymbol: ({
      [Symbol('foo')/* trying to lookup for the symbol */]: foo,
    }) => foo,
  };
  const { canAccessSymbol, cantAccessSymbol } =createInjector(manifest)();
  t.eq(canAccessSymbol, 'foo');
  t.eq(cantAccessSymbol, undefined, 'could not resolve the symbol');
});

Going further: make sure we can swap injectable implementation depending on the context

The current implementation is fine for all the dependency graphs you already know prior to the execution of the program. However, in practice you will likely have “late binding”: you will only know the implementation of a given injectable to use at run time, based on the execution context. In some cases, you might also want to overwrite the default implementations provided. Remember, when dealing with dependency injection you must think with interfaces and abstract types !

For example, in a web server you could bind your injectables to the user related to the current incoming request (and as so, avoiding security concerns on who accesses the resources). You can also use a specific injectable implementation depending on the profile of the user, their location, etc.

To solve theses use cases we are going to make our injector a function which can define/overwrite some specific factories to allow late dependency binding.

export const createInjector = (injectableFactoryMap) => {
  // (1) The injector is now wrapped within a function
  return function inject(lateDeps = {}) {
    const injectables = {};
    const propertyDescriptors = mapValues(createPropertyDescriptor);

    Object.defineProperties(
      injectables,
      propertyDescriptors({
        ...injectableFactoryMap,
        ...lateDeps, // (2) you can overwrite already defined factories or create late bindings
      })
    );

    return injectables;

    function createPropertyDescriptor(factory) {
      const actualFactory =
        typeof factory === 'function' ? factory : valueFn(factory); // (3) Syntactic sugar
      return {
        get() {
          return actualFactory(injectables);
        },
        enumerable: true,
      };
    }
  };
};

The main differences are:

1. We wrap the injector within a function so we can invoke the dependency resolution multiple times
2. The manifest can be extended or overwritten later on
3. The manifest now accepts any value which is not a factory function: the injector wraps it automatically (this is just for convenience)

This implementation should comply with the following specifications:

import { test } from 'zora';
import {createInjector} from './di.js';

const defaultUser = { name: 'John' };

const inject =createInjector({
  Greeter: ({ user }) => ({
    greet() {
      return `Hello ${user.name}`;
    },
  }),
  user: defaultUser,
});

test(`Use default injectable instances as provided by the manifest`, (t) => {
  const { Greeter } = inject();
  t.eq(Greeter.greet(), 'Hello John');

  t.ok(
    Greeter !== inject().Greeter,
    'should return a different instance on every invocation'
  );
});

test(`Overwrite dependencies at invocation time`, (t) => {
  t.eq(inject().Greeter.greet(), 'Hello John');
  t.eq(
    inject({
      user: {
        name: 'Bob',
      },
    }).Greeter.greet(),
    'Hello Bob'
  );
  t.eq(
    inject({
      user: {
        name: 'Raymond',
      },
    }).Greeter.greet(),
    'Hello Raymond'
  );
});

Recursivity: Injecting the injector function

In some cases, a injectable may need to inject its dependency graph into one of its own functions. We could make that injectable build its own manifest and injector, but that would mean mixing several responsibilities and leaking implementation details of the injector/registration system: ie going backward compared to what we have built so far.

Instead we can simply make sure an injector get injected itself and therefore allows recursive calls.

Let’s see the point with a typical use case:

You have a client to access a database such node-pg for postgresql. For efficiency, your client will actually be a pool of clients which abstracts away the internals.

db.query(`SELECT * FROM table`)

When you make such a call you don’t really care whether the client comes from a pool, is already connected, etc. You just want to declare the intention: you want to perform a database query. However if your intention is to run a SQL transaction the client must be the same, holding a session and eventually wrapping the rollback on error etc.

import pg from 'pg';
import {createClient} from './client.js';
import { createClient} from './db.js'; // simple wrapper around the raw driver

export const createConnectionPool= (conf) => {
  const pool = new pg.Pool(conf);
  return {
    // ... some db interface 
    // ...
    async withinTransaction(fn) {
      const client = await pool.connect();
      try {
        await client.query('BEGIN');
        const result = await fn({ db:createClient({ client }) });
        await client.query('COMMIT');
        return result;
      } catch (e) {
        await client.query('ROLLBACK');
        throw e;
      } finally {
        client.release();
      }
    },
  };
};

You’ll use with a client function as so:

await db.withinTransaction(function clientFn({ db }) {
    // transaction bound code using the local "db" client
    db.query(query1);
	  db.query(query2); //etc
});

This is fine for low level calls, but in practice you’ll use higher level services which depend on an abstract database client. Therefore, you will have to make sure to bind them to the transaction bound db client instance, which imply calling the factories from the clientFn … and you are now facing the caveats we saw at the beginning of this article.

import {createUsersService} from './user.js'
import {createAuthorizationService} from './authorization.js'

await db.withinTransaction(async function clientFn({ db }) {
    // bind services to the transaction session
    const Users = createUsersService({db});
    const Authorization = createAuthorizationService({Users});
    // etc
});

With the following implementation of the injector

export constcreateInjector= (injectableFactoryMap) =>
// (1) the returned function is named "inject"
  function inject(args = {}) {
    // ...

    Object.defineProperties(
      injectables,
      propertyDescriptors({
        ...injectableFactoryMap,
        inject: valueFn(inject), // (2) we inject the "inject" function !
        ...args,
      })
    );

    // ...

   
  };

You are now able to recursively call the inject function as it is added to the dependency graph (2):

const bindToInjectables =
  (db) =>
	// (1)
  ({ inject }) => ({
    ...db,
    // (2) overwrite the implementation of the db "withinTransaction" method
    withinTransaction: (fn) =>
      // (3) delagate to the actual implementation ...
      db.withinTransaction(({ db }) =>
        // (4) but calling the client function with the injectables bound to the transaction client
        fn(
          inject({
            db: bindToInjectables(db),
          })
        )
      ),
  });

// ...

const inject = createInjector(manifest); 

// ...

// const db = getting db from somewhere
const injectables = inject({ db: bindToInjectables(db) })

The function bindToInjectables takes a db object and returns a new factory to pass to a manifest or to the inject function for late binding:

1. As any registered factory it gets the injectables… including the inject function itself
2. we overwrite the provided db instance
3. withinTransaction delegates the call
4. calling the client function with all the dependencies where db refers here to the transaction bound client.

import { test } from 'zora';
import { createInjector } from './lib/di/injector.js';

const createDB = (depth = 0) => {
  return {
    depth,
    withinTransaction: (fn) => {
      return fn({ db: createDB(depth + 1) });
    },
  };
};

const serviceFactory = ({ db }) => {
  return {
    foo() {
      return db.depth;
    },
  };
};

const inject = createInjector({
  A: serviceFactory,
});

test('withinTransaction should scope the clientFn to a given db instance', (t) => {
  const { A, db } = inject({ db: createDB() });
  t.eq(A.foo(), 0, 'should have the default depth');
  t.eq(
    db.withinTransaction(({ db }) => {
      return serviceFactory({ db }).foo()
    }),
    1,
		'child db client'
  );
});

test('Injector binds clientFn to the local db context', (t) => {
  const bindToInjectables =
    (db) =>
    ({ inject }) => {
      return {
        ...db,
        withinTransaction: (fn) =>
          db.withinTransaction(({ db }) => {
            return fn(
              inject({
                db: bindToInjectables(db),
              })
            );
          }),
      };
    };

  const { A, db } = inject({ db: bindToInjectables(createDB()) });
  t.eq(A.foo(), 0, 'should have the default depth');
  t.eq(
    // A is injected into the transaction function
    db.withinTransaction(({ A }) => {
      return A.foo();
    }),
    1,
    'local A is bound to child client (depth 1)'
  );
});

Icing on the cake: improve the dev experience

We have already improved the developer experience by giving the ability to inject anything (not only a factory function). But the current component can fail if there is a missing dependency giving a quite unhelpful error:

import {createInjector} from './lib/di/injector.js';

const injector =createInjector({});

const { A } = injector();

A.foo();// BOOM: Cannot read properties of undefined (reading 'foo')

By using a proxy we can trap the getters’ calls and detect if a token does not exist in the dependency graph, giving a more helpful feedback to the developer.

export const createInjector= (injectableFactoryMap) =>
  function inject(args = {}) {
    const target = {};

    // (1) injectables is now a proxy 
    const injectables = new Proxy(target, {
      get(target, prop, receiver) {
        if (!(prop in target)) {
          throw new Error(`could not resolve factory '${prop.toString()}'`);
        }
        return Reflect.get(target, prop, receiver);
      },
    });

    const propertyDescriptors = mapValues(createPropertyDescriptor);

    Object.defineProperties(
      target,
      propertyDescriptors({
        ...injectableFactoryMap,
        inject: valueFn(inject),
        ...args,
      })
    );

    return injectables;

    function createPropertyDescriptor(factory) {
      const actualFactory =
        typeof factory === 'function' ? factory : valueFn(factory);
      return {
        get() {
          return actualFactory(injectables);
        },
        enumerable: true,
      };
    }
  };

In (1) we trap all the calls to any getter to first check if the injectable has been defined. If not we throw an error: the same code as above will print: could not resolve factory 'A'

There is a caveat though: you can’t use default values when declaring your factories. The following test will not pass:

test(`A factory with default values should resolve to those values`, (t) => {
  try {
    const { a } = createInjector({
      a: ({ b = 'foo' }) => b,
    });
    t.eq(a, 'foo', 'resolve default values');
  } catch (err) {
    t.fail('should not have thrown');
  }
});

Conclusion

In this essay, we have seen what dependency injection is and how it can help to build better software. We implemented a fairly robust and flexible DI container(injector) in a few lines of code thanks to the meta-programming features of Javascript. This component does not depend on any framework. You can see an example of a web server (based on Fastify) using this DI component in this repository. Details are given in the readme.

What is a pure function, why is it interesting and how do we use them at Indy?

What is a pure function?

A pure function has two properties :

1. Output depends only on input
2. No side effects

Output depends only on input

Output only depends on input, no matter when or where you call the function in your code.

To implement such a function, you could simply map input to output.

const square = {
	0: 0,
	1: 1,
	2: 4,
	3: 9,
	4: 16,
	…
};

square[2]; // is always 4

Writing all possible pairs (input, output) can be tedious. So you calculate the output from the input

const square = x => x * x;
square(2); // is always 4

These two implementations of square are equivalent and you always have

square(2) = square(2)

On the contrary, Math.random() is impure as the output depends on when it is called.

Math.random() ≠ Math.random()

No side effects

A side effect is an observable effect other than returning a value:

• I/O operation
  • Writing to database or file
  • making an HTTP call
  • Logging
  • Printing on screen
• Mutation

Being pure means leaving I/O operations outside of the function and using immutability.

const a = square(2) is equivalent to const a = 4

Nothing happens during the computation of square(2) other than returning 4.

An implementation with side effect could be

const impureSquare = x => {
	console.log('square', x);
	return x * x;
};

const a = impureSquare(2) is not equivalent to const a = 4

Why is it interesting?

As output only depends on input without side effects, pure functions are independent of time and state. Pure functions are predictable.

Referentially transparent

An expression is referentially transparent when it may be replaced by its value without changing the result of the program. It makes the code easier to read, understand and test.

const add2 = x => x + 2;
const multiplyBy2 = x => x * 2;
const add2AndMultiplyBy2 = x => multiplyBy2(add2(x));

const result = add2AndMultiplyBy2(3);
// is equivalent to
const result = multiplyBy2(5);
// is equivalent to
const result = 10;

Testable

Pure functions are easily testable.

const tomorrow = today => today.add({ days: 1 });

// You simply test it with
expect(tomorrow(Temporal.PlainDate.from(‘2022-05-28’)))
	.toEqual(Temporal.PlainDate.from(‘2022-05-29’));

What if it were an impure function?

const impureTomorrow = () => {
	const today = Temporal.Now.plainDateISO();
	return today.add({ days: 1 });
};

Impure function is tricky to test as you have to mock Temporal.Now.plainDateISO().

Cacheable

Pure function output is cacheable. Simply map input to output and the next time you need the result of this extensive function call, use the cached value. No need to worry about time to live.

To do that, you can use memoization. Here is a basic implementation:

const memoize = (f) => {
	const cache = {};
	
	return (...args) => {
		const key = JSON.stringify(args);
		
		if (key in cache) {
			return cache[key];
		}
		
		const result = f(...args);
		cache[key] = result;
		return result;
	};
};

const memoizedSquare = memoize(square);

memoizedSquare(2); // is 4. It calls square()
memoizedSquare(2); // is 4. It uses the cached result. Doesn’t call square()

Runnable in parallel

Pure functions can run in parallel as no access to shared memory means no race condition.

How do we use them at Indy?

Due to the power of pure functions, we use them at Indy.

We have two kind of functions:

• model functions (pure) contain all the logic of the application
• service functions (impure) handle I/O operations

Model functions

Model functions are pure and contain all the logic of the application. No logic should be in impure functions.

• Calculating business (mainly bookkeeping) rules
• Mapping data at interfaces (business model / database, business model / web)

Service functions

Service functions gather data, use model functions and save results. No logic here.

async function doSomething() {
	const data = await getData();
	// all the logic is in this pure function from the model
	const result = computeSomething(data);
	await saveResult(result);
}

“Tu sais pas quoi ? Je viens au bureau mardi !”

Ou : où, comment et pourquoi télétravailler.

---

La question du rapport entre un pangolin et le cours de l’action des GAFAM peut vous sembler rhétorique aujourd’hui, à tête reposée et nez récuré (maintes fois). Mais il y a 3 ans à peine, on vous a peut-être ri au nez quand vous avez tenté subtilement d’aborder la question de l’intérêt de vous avoir équipé d’un pc portable si celui-ci est systématiquement accroché au même bureau — et ce, au bureau justement —

Alors forcément aujourd’hui en parlant de télétravail et vu l’Histoire, on pourrait croire que je m’attaque vaillamment à l’invention de l’eau tiède. Tout a été dit. Tout ? Non ! Un village peuplé d’irréductibles gaulois résiste encore et toujours à l’envahisseur. Je discutais avec un ami pas plus tard qu’il y a 3 jours, un ami qui me disait que son but à court terme était d’apprendre à télétravailler.

Drôle d’idée non ?

Pourtant c’est un réel besoin pour lui, et ce malgré son doctorat en informatique, ses années d’expérience et la promotion des bonnes pratiques omniprésente dans son travail (le genre de gars à avoir toute sa CI rouge si il manque une Docstring, si vous voyez ce que j’veux dire).

Parce qu’il ne considère pas le télétravail comme une évidence, et encore moins comme étant gagné d’avance.

Et vous savez quoi ? Je pense sincèrement qu’il a raison. Et que j’ai eu tort.

---

Les lecteurs attentifs de ce blog savent que j’ai toujours travaillé dans l’écosystème dit “startup”. Et pour moi le télétravail a toujours été un acquis. J’ai même commencé ma carrière dans un coworking avec mon CTO à ma droite et une autre société sur le bureau d’en face.

Quoi ? Mais dans un coworking on est au bureau ! Ça n’est pas du télétravail !

Alors si. Télétravail n’est pas synonyme de travail à la maison, et aujourd’hui on va se baser sur la définition suivante :

💡 Télétravail === travail ailleurs que dans des locaux propres à l’entreprise de l’employé·e.

Comme dans tous les jeux sociétaux, on n’a clairement pas tou·te·s les mêmes cartes. Et les privilèges, comme partout, ça change la donne. Ce n’est pas les gens coincés au RDC d’un immeuble borgne pendant que leur collègue prend le soleil du Sud sur la terrasse de son AirBnB de troisième confinement qui me diront le contraire. Et la visioconférence du lundi matin n’arrangera en rien les choses pour celleux pour qui l’Arcep utilise le terme “zone blanche” et qui disposent donc d’un débit internet proche du transport de disquettes 3,5” à dos de tortue.

Alors attention, je fais le malin à utiliser de belles métaphores, mais bien sûr ce que je dis ici ne s’applique globalement qu’aux employé·e·s de bureau. Parce que pour la personne qui bosse à l’usine, le problème de débit internet pour la visio ça la fait doucement rigoler (sous le masque).

Mais même si on se cantonne à ce que j’ai principalement connu jusqu’à maintenant, on a déjà du grain à moudre. À commencer par le café. Prenez-en un d’ailleurs, ou un thé. Ou une bière si vous n’êtes pas au bureau.

---

Comme souvent, le télétravail peut fonctionner très bien comme très mal. Et je sais de quoi je parle, j’ai essayé les deux (pour toi public). L’important ici c’est de trouver son équilibre. Et cet équilibre n’est pas le même pour tout le monde ! Vous me direz, travailler systématiquement au bureau ne correspond pas à tout le monde non plus. Et vous aurez raison. Et je vous dirai oui ! Oui, et c’est l’intérêt majeur de la démocratisation du télétravail. Permettre à chacun de trouver l’équilibre idoine entre les différentes contraintes et avantages de chaque mode de fonctionnement.

Parce que tout n’est pas rose en remote, et tout n’est pas gris au bureau. Loin de là.

Je parlais d’équilibre pro / perso dans mon précédent billet, et le télétravail est un vrai bonus pour l’atteindre… quand bien utilisé. Sinon c’est une calamité qui va venir vous chercher au fond du lit (ou pire, au bar) pour le meet de 20h45.

Il faut cependant bien admettre que plus de souplesse peut s’avérer précieuse sans porter préjudice à la sacro-sainte productivité (bien au contraire). Un exemple tout bête ? Votre créneau de livraison de colis s’étend de 8h lundi à 19h lundi (d’après) ? Ça serait dommage de poser 8 CP pour les 4 minutes d’interruption effective de votre travail non ? Un autre exemple : les rdv médicaux qui nécessitent très rarement 8h d’absence et ne se soldent que trop souvent par une journée de congé sans solde.

À l’opposé du spectre on trouve malheureusement bien des désagréments. Le principal étant bien souvent lié au télétravail… à la maison. En effet, quand le télétravail est subi et non choisi, on est très rarement équipé correctement pour le faire chez soi. Très pragmatiquement, on peut citer l’équipement informatique (écran externe, périphériques dédiés, etc…) ainsi que le bureau et son fauteuil, un minimum ergonomique s’il vous plaît selon la médecine du travail. Mais le plus important dans le télétravail à domicile, ce qui peut transformer le tout en cauchemar, c’est bien un bureau. La pièce je veux dire. Rien de tel que de travailler sur son canapé ou dans son lit conjugal pour déclencher, subir puis haïr l’invasion de sa sphère personnelle par le boulot. La frontière jusqu’alors bien définie va finir par se flouter puis disparaître, et là adieu le droit à la déconnexion !

Et n’oublions pas les coûts financiers imputés aux factures perso par les activités pro ! 8h par jour de consommation électrique, internet, et les 17 cafés quotidiens sur la petite machine domestique, ça finit par s’accumuler au bout de 52 semaines ! D’aucuns diraient que ces factures devraient être réglées par l’entreprise au prorata de l’utilisation professionnelle, et ils auraient bien raison…

Vous me sentez amer peut-être, mais je suis pourtant un fervent défenseur du télétravail. Parce que j’ai un bureau dédié à la maison ! Les 50 minutes de train entre celle-ci à la campagne et le bureau d’Indy n’y sont pas pour rien non plus (coucou les pauvres parisiens prisonniers du RER).

Mais ce n’est pas pour autant que je prône le full-remote, ou l’absence de locaux dédiés. Bien au contraire, je suis ravi de faire les trajets hebdomadaires et de voir les collègues ailleurs que sur mon écran ! Je suis ravi de partager tous ces moments et interactions ailleurs que sur Slack. Je suis ravi de pouvoir dessiner au tableau blanc pour présenter ma dernière idée farfelue ou qu’on m’explique un détail d’architecture. Je suis ravi de rencontrer la dernière promo d’indies, fraîchement débarquée en début de mois (ah oui, on recrute toujours “un peu” par ici !).

Mais je suis aussi ravi d’éviter l’heure de pointe à Part-Dieu le lundi matin, je suis très content d’avoir la vue sur la forêt depuis mon poste, je préfère dépenser mes tickets-restau au restau qu’à la boulangerie du coin, et surtout, surtout, en bon geek du café le mien est meilleur que celui du bureau 🙃. Mais il n’est pas offert par Indy. Tout est question d’équilibre qu’il vous disait le mec au début de l’article.

Vous aurez peut-être compris maintenant que je ne suis pas là pour plaider une organisation du travail ou l’autre, mais bien les deux ! Les deux à la fois, les deux parfois, l’une ou l’autre selon les besoins de chacun et chaque situation, en bonne intelligence. Car parfois il ne faut que ça : du bon sens. Et j’espère sincèrement qu’à la fin de la pandémie — d’ici 2043 — quand tout sera revenu à la normale, on n’aura pas l’idée saugrenue de faire un bond en arrière vers les normes obsolètes d’hier. Et je me prends à parier qu’on continuera à faire des pas de côté et à joyeusement démonter les mauvaises habitudes jusque là accumulées.

Et toi alors ? Toi derrière ton écran sur ton canapé ou dans ton box. Tu paries avec moi ? Ou contre moi…