Contribution guidelines

Welcome to the mediateur repository 🖖

First of all, thank you for spending some time to improve the project 🙏! In this documentation, you will find all the useful information to help you contribute to the project.

Introduction

TypeScript

• Programming style
• Naming conventions
• Code conventions

🏁 Introduction

The following guidelines ensure your contributions respect the project philosophy, design, conventions and rules.

🏷️ TypeScript

Programming style

• Don't use classes, except to define errors
• Use type inference as much as possible.
• Don't use .d.ts file even for defining type aliases.
• Don't use anonymous types.
• Don't use generator.
• Don't resolve Promise manually, use async/await instead.
• Don't use default export.
• All instructions need to be ended with semicolon (;).
• Use trailing comma.

Naming convention

• Type alias name must use the PascalCase naming convention:

type MessageHandler = {};

• All TypeScript files need to be named with the camelCase convention (eg: messageHandler.ts).

• Variables, functions and parameters must use the camelCase naming convention 🐪:

const messageType = ["createUserMessage", "updateUserMessage"];

• If you define a constant with a symbol, use the UPPER_SNAKE_CASE_CONVENTION 🐍:

const SCENARIO_KEY = Symbol("parse");

• Don't suffix type aliases with the Type word:

// don't
type MessageHandlerType = {
  // ...
};

// do
type MessageHandler = {
  // ...
};

• Don't prefix interfaces with the I character:

// don't
interface IMessageHandler {
  // ...
}

// do
interface MessageHandler {
  // ...
}

• Don't use the T character to define a generic, use a name with the T prefix to make the code easier to understand:

// don't
const handlerRegistry: Map<string, T> = new Map();

// do
const handlerRegistry: Map<string, TMessageHandler> = new Map();

Code conventions

• To avoid scope issues, don't use the function keyword, use arrow function instead:

// don't
function send(message: Message) {
  // ...
}

// do
const send = (message:Message) => {
  // ...
};

• Always use arrow function for callbacks:

// don't
[1, 2, 3, 4].map(function (nb: number) {
  const pow = nb * nb;
  return pow;
});

// do (we can do better, see next rule)
[1, 2, 3, 4].map((nb: number) => {
  const pow = nb * nb;
  return pow;
});

• If you have a single instruction that returns sometings, use the short syntax:

// don't
[1, 2, 3, 4].map((nb: number) => {
  return nb * nb;
});

// do (we can do better, see next rule)
[1, 2, 3, 4].map((nb: number) => nb * nb);

• If function parameters can be infer, do not specify the type:

// don't
[1, 2, 3, 4].map((nb: number) => nb * nb);

// do (we can do better, see next rule)
[1, 2, 3, 4].map((nb) => nb * nb);

• Always use const for immutability (never use let without a really good reason).
• Try to not use the any type. If you don't know the real type, use unknown type instead.
• Don't use enumerations. TypeScript will emulate this feature because it's not part of the ECMAScript specification. Instead you can use a type alias with some union (it will not generate anything during compilation).
• Don't use Function as a type.