DEV Community: ecyrbe

Advent of typescript 2023 day 23 : Connect 4

ecyrbe — Sat, 23 Dec 2023 15:56:55 +0000

Hello Typescript Wizards, i hope you are having fun with the Advent of Typescript 2023.
This is the third article in the series of blog posts explaining the solutions to the challenges
for advent of typescript 2023.

The challenge

Playing the game is done by calling the Connect4 Utility type with the current game state and the next row position for the chip color of the current player.
The utility type will return the next game board and state.

Example

  Expect<
    Equal<
      Connect4<NewGame, 0>,
      {
        board: [
          ['  ', '  ', '  ', '  ', '  ', '  ', '  '],
          ['  ', '  ', '  ', '  ', '  ', '  ', '  '],
          ['  ', '  ', '  ', '  ', '  ', '  ', '  '],
          ['  ', '  ', '  ', '  ', '  ', '  ', '  '],
          ['  ', '  ', '  ', '  ', '  ', '  ', '  '],
          ['🟡', '  ', '  ', '  ', '  ', '  ', '  ']
        ];
        state: '🔴';
      }
    >
  >,

Solution to place a chip on the board

Here we will follow a step by step approach to solve this challenge.

Step 1: Find the first empty row in a column

To place a chip on the board we first need to find the first empty row in the column.
Then we can replace the empty cell with the chip color of the current player.

type FindEmptyRow<
  board extends Connect4Cell[][],
  column extends number
> = board extends [
  ...infer rows extends Connect4Cell[][],
  infer row extends Connect4Cell[]
]
  ? row[column] extends '  '
    ? rows['length']
    : FindEmptyRow<rows, column>
  : never;

Step 2: Replace a cell in a matrix

This is much like the Tic-Tact-Toe challenge where we had to replace a cell in a matrix.

type ArrayReplaceAt<Array extends any[], X extends number, value> = {
  [key in keyof Array]: key extends `${X}` ? value : Array[key];
};

type MatrixReplaceAt<
  Matrix extends any[][],
  Position extends [number, number],
  value
> = {
  [key in keyof Matrix]: key extends `${Position[1]}`
    ? ArrayReplaceAt<Matrix[key], Position[0], value>
    : Matrix[key];
};

Step 3: Place a chip on the board

We can now place a chip on the board by combining the previous steps.
Notice 1: We use chip extends Connect4Chips to check that the chip is not a win or a draw.
Notice 2: We use Extract to cast the result to Connect4Cell[][] since typescript has a hard time to infer the type.

type PlaceChip<
  board extends Connect4Cell[][],
  column extends number,
  chip extends Connect4State
> = chip extends Connect4Chips
  ? FindEmptyRow<board, column> extends infer row extends number
    ? Extract<MatrixReplaceAt<board, [column, row], chip>, Connect4Cell[][]>
    : board
  : board;

Solution to check if the game is won

Now that we can place a chip on the board, we can check if the game is won.
This is a lot like the previous days challenges.

We will first create small utility types to get a row, column or diagonal from the board.
Then we will check if there is a winner in the rows, columns or diagonals.

Step 1: Enabler

The first step is to create a common type to check if a tuple contains 4 same chips in a row.
For that we use recusion and accumulate the chips in a tuple until we have 4 chips.
If we switch to a different chip, we reset the accumulator.

type Check4<
  Board extends Connect4Cell[],
  $acc extends Connect4Chips[] = []
> = $acc['length'] extends 4
  ? $acc[0]
  : Board extends [infer head, ...infer tail extends Connect4Cell[]]
  ? head extends Connect4Chips
    ? [$acc[0]] extends [head]
      ? Check4<tail, [...$acc, head]> // continue accumulating the same chips
      : Check4<tail, [head]> // reset accumulator to the new chip
    : Check4<tail> // reset accumulator
  : never;

Step 2: Check if rows are won

Get a row as a tuple

To check if a row is won, we need to get the row. This is done with a simple indexed type:

type GetRow<
  Board extends Connect4Cell[][],
  Row extends number
> = Board[Row];

Find winner in rows

Now that we can get a row, we can check if all the rows are won by iterating with the Check4 type over the rows.
For that we use Distributive conditional types.

type WinnerInRows<
  Board extends Connect4Cell[][],
  $rows = ToInt<keyof Board>
> = $rows extends number ? Check4<GetRow<Board, $rows>> : never;

Step 3: Check if columns are won

Get a column as a tuple

To check if a column is won, we need to get the column. This is done by using a Mapped type:

type GetColumn<Board extends Connect4Cell[][], column extends number> = {
  [key in keyof Board]: Board[key][column];
};

Find winner in columns

It's the same as rows now :

type WinnerInColumns<
  Board extends Connect4Cell[][],
  $columns = ToInt<keyof Board[0]>
> = $columns extends number ? Check4<GetColumn<Board, $columns>> : never;

Step 4: Check if diagonals are won

This is a lot like the previous days challenges. We will create a Map to get the diagonal cells from the board.
Then we will check if there is a winner in the diagonals.

Map of diagonals

We can see that we have 12 diagonals in the board. We can create a map of all the diagonals.

type DiagonalMap = [
  [[0, 3], [1, 2], [2, 1], [3, 0]],
  [[0, 4], [1, 3], [2, 2], [3, 1], [4, 0]],
  [[0, 5], [1, 4], [2, 3], [3, 2], [4, 1], [5, 0]],
  [[0, 6], [1, 5], [2, 4], [3, 3], [4, 2], [5, 1]],
  [[1, 6], [2, 5], [3, 4], [4, 3], [5, 2]],
  [[2, 6], [3, 5], [4, 4], [5, 3]],
  [[2, 0], [3, 1], [4, 2], [5, 3]],
  [[1, 0], [2, 1], [3, 2], [4, 3], [5, 4]],
  [[0, 0], [1, 1], [2, 2], [3, 3], [4, 4], [5, 5]],
  [[0, 1], [1, 2], [2, 3], [3, 4], [4, 5], [5, 6]],
  [[0, 2], [1, 3], [2, 4], [3, 5], [4, 6]],
  [[0, 3], [1, 4], [2, 5], [3, 6]]
];

Get a diagonal as a tuple

This a now a lot like the previous days challenges. We will use the map to get the diagonal cells from the board.

type GetDiagonal<
  Board extends Connect4Cell[][],
  N extends number,
  $map extends [number, number][] = DiagonalMap[N]
> = Extract<
  {
    [key in keyof $map]: Board[$map[key][0]][$map[key][1]];
  },
  Connect4Cell[] // cast
>;

Find winner in diagonals

This is straight forward now, same as rows and columns

type WinnerInDiagonals<
  Board extends Connect4Cell[][],
  $diags = ToInt<keyof DiagonalMap>
> = $diags extends number ? Check4<GetDiagonal<Board, $diags>> : never;

Step 5: Check if the game is won

We can now check if the game is won by combining the previous steps.

type Winner<Board extends Connect4Cell[][]> =
  | WinnerInRows<Board>
  | WinnerInColumns<Board>
  | WinnerInDiagonals<Board>;

Solution to check if the game is a draw

To check if the game is a draw, we need to check if there is an empty cell in the board.
That's it.

type CheckDraw<Board extends Connect4Cell[][]> =
  '  ' extends Board[number][number] ? false : true;

Implementing the Connect4 Utility type

Step 1: Next game state

Now that we have all the utilities to check if there is a winner or a draw, we can check the next game state.

type NextGameState<
  Board extends Connect4Cell[][],
  State extends Connect4State,
  $winner extends Connect4Chips = Winner<Board>
> = [$winner] extends [never]
  ? CheckDraw<Board> extends false
    ? State extends '🔴'
      ? '🟡'
      : '🔴'
    : 'Draw'
  : `${$winner} Won`;

Step 2: Implement the Connect4 Utility type

Now that we have can place a chip on the board and get the next game state, we can implement the Connect4 Utility type.

type Connect4<
  Game extends { board: Connect4Cell[][]; state: Connect4State },
  Column extends number,
  $NewBoard extends Connect4Cell[][] = PlaceChip<
    Game['board'],
    Column,
    Game['state']
  >,
  $NewState = NextGameState<$NewBoard, Game['state']>
> = {
  board: $NewBoard;
  state: $NewState;
};

Conclusion

We used the same approach as the previous days challenges.
One thing to remember, don't hesitate to build Map types to simplify your code.
Take advantage of Distributive conditional types to iterate over a tuple.

You can find the full solution on Ts Playground

This was a fun challenge. I hope you enjoyed it as much as i did.
We will continue with the next challenge tomorrow.

Advent of typescript 2023 day 22 : Reindeer Sudoku

ecyrbe — Fri, 22 Dec 2023 14:12:26 +0000

Hello Typescript Wizards, i hope you are having fun with the Advent of Typescript 2023.
This is the second article in the series of blog posts explaining the solutions to the challenges for advent of typescript 2023.

Description

This challenge is about creating a special Sudoku checker in typescript type system.
For this we are given some simple types to describe a game of Reindeer Sudoku.

type Dasher = '💨';
type Dancer = '💃';
type Prancer = '🦌';
type Vixen = '🌟';
type Comet = '☄️';
type Cupid = '❤️';
type Donner = '🌩️';
type Blitzen = '⚡';
type Rudolph = '🔴';

type Reindeer = Dasher| Dancer| Prancer| Vixen| Comet| Cupid| Donner| Blitzen| Rudolph;

The challenge

The challenge is to create one utility type that checks if a given Sudoku board is valid.
The utility type should take a Sudoku board and return a boolean indicating if the board is valid.
A valid board is a board where each row, column and 3x3 square contains all 9 reindeers.

Here is an example of a valid Sudoku board:

type SudoKu = [
  [['💨', '💃', '🦌'], ['☄️', '❤️', '🌩️'], ['🌟', '⚡', '🔴']],
  [['🌟', '⚡', '🔴'], ['💨', '💃', '🦌'], ['☄️', '❤️', '🌩️']],
  [['☄️', '❤️', '🌩️'], ['🌟', '⚡', '🔴'], ['💨', '💃', '🦌']],
  /*------------------------------------------------------*/
  [['🦌', '💨', '💃'], ['⚡', '☄️', '❤️'], ['🔴', '🌩️', '🌟']],
  [['🌩️', '🔴', '🌟'], ['🦌', '💨', '💃'], ['⚡', '☄️', '❤️']],
  [['⚡', '☄️', '❤️'], ['🌩️', '🔴', '🌟'], ['🦌', '💨', '💃']],
  /*------------------------------------------------------*/
  [['💃', '🦌', '💨'], ['❤️', '🌟', '☄️'], ['🌩️', '🔴', '⚡']],
  [['🔴', '🌩️', '⚡'], ['💃', '🦌', '💨'], ['❤️', '🌟', '☄️']],
  [['❤️', '🌟', '☄️'], ['🔴', '🌩️', '⚡'], ['💃', '🦌', '💨']]
];

Solution

Here we will follow a step by step approach to solve this challenge.

Step 1: Enabler

The first step is to create a utility type that flattens the board.
Indeed, we will need to check each column and it's easier to do it with a flat array.

Flatten a matrix into a tuple

Here is a utility type that flattens a matrix into a tuple, doing it recursively:

type Flatten<T extends any[][], $acc extends any[] = []> = T extends [
  infer Head extends any[],
  ...infer Tail extends any[][]
]
  ? Flatten<Tail, [...$acc, ...Head]>
  : $acc;

Flatten a Sudoku board

To flatten a Sudoku board, we just need to flatten each row of the board.
For this we use a mapped type:

type FlattenSudoku<Sudoku extends Reindeer[][][]> = {
  [Row in keyof Sudoku]: Flatten<Sudoku[Row]>;
};

Check duplicate reindeers

We need to check if a row, column or 3x3 square contains all the reindeers.
We can handle all the cases with a simple utility type:

type CheckDuplicates<Cells extends Reindeer> = Reindeer extends Cells
  ? true
  : false;

Step 2: Check if rows are valid

Now that we have a flat array, we can check if a row is valid.
For this we need to check if the row contains all the reindeers.

Get a row as a union

To check if a row is valid, we need to get the row. This is done with a simple indexed type:

type GetRow<
  Sudoku extends Reindeer[][],
  Row extends number
> = Sudoku[Row][number];

Check rows

Now we just need to use the CheckDuplicates utility type to check if the row contains all the reindeers.
And we use Distributive Conditional Types to check all the rows at once.

type CheckRows<
    Sudoku extends Reindeer[][],
    $Iter extends number = ToInt<keyof Sudoku>,
> = $Iter extends number ? CheckDuplicates<GetRow<Sudoku, $Iter>> : false;

Step 3: Check if columns are valid

Get a column as a union

To check if a column is valid, we need to get the column. We simply use indexed types again:

type GetColumn<
  Sudoku extends Reindeer[][],
  Column extends number
> = Sudoku[number][Column];

Check columns

Same logic as rows, we use Distributive Conditional Types to check all the columns at once.

type CheckColumns<
  Sudoku extends Reindeer[][],
  $Iter extends number = ToInt<keyof Sudoku>
> = $Iter extends number ? CheckDuplicates<GetColumn<Sudoku, $Iter>> : false;

Step 4: Check if 3x3 squares are valid

Map of 3x3 squares

Checking if a 3x3 square is valid is a bit more complicated.
We need to get the 3x3 square from the board and check if it contains all the reindeers.
For that we need a map of all the 3x3 squares.

type MapBox<N extends number> = [
  [[0, 0], [1, 0], [2, 0]],
  [[3, 0], [4, 0], [5, 0]],
  [[6, 0], [7, 0], [8, 0]],
  [[0, 1], [1, 1], [2, 1]],
  [[3, 1], [4, 1], [5, 1]],
  [[6, 1], [7, 1], [8, 1]],
  [[0, 2], [1, 2], [2, 2]],
  [[3, 2], [4, 2], [5, 2]],
  [[6, 2], [7, 2], [8, 2]]
][N];

Get one 3x3 square as a union

Now we can use the MapBox to get the 3x3 square cells from the board and check if the 3x3 square is valid.
Again we use indexed types with the Map to get the 3x3 square.

type GetBox<
  Sudoku extends Reindeer[][][],
  N extends number,
  $Map extends number[][] = MapBox<N>
> = Sudoku[$Map[number][0]][$Map[number][1]][number];

Check 3x3 squares

Same logic as rows and columns, we use Distributive Conditional Types to check all the 3x3 squares at once.

type CheckBoxes<
  Sudoku extends Reindeer[][][],
  $Iter extends number = ToInt<keyof Sudoku>
> = $Iter extends number ? CheckDuplicates<GetBox<Sudoku, $Iter>> : false;

Step 5: Check if the board is valid

Now that we have all the utilities to check if a row, column or 3x3 square is valid, we can check if the board is valid.

Helper to convert a number literal to a number

We need a helper to convert a number literal to a number. That is to check all the rows, columns and 3x3 squares.

type ToInt<T> = T extends `${infer N extends number}` ? N : never;

Check the board

One thing to note here, if the board is valid, all tests return true else it returns true|false, so we just need to check for truthyness of all cases.

type Validate<
  Sudoku extends Reindeer[][][],
  $flattenSudoku extends Reindeer[][] = FlattenSudoku<Sudoku>
> =
  | CheckRows<$flattenSudoku>
  | CheckColumns<$flattenSudoku>
  | CheckBoxes<Sudoku> extends true
  ? true
  : false;

Conclusion

We have created a utility type that checks if a given Sudoku board is valid.

You can find the full solution on Typescript Playground

Hope you enjoyed this challenge, see you tomorrow for the next one.

Advent of Typescript 2023 Day 21 : TIC TAC TOE

ecyrbe — Thu, 21 Dec 2023 12:34:41 +0000

Hello Typescript Wizards, i hope you are having fun with the Advent of Typescript 2023.
With Trash we created some awesome challenges for you to solve this year.
I'm starting to do Blog posts to explain the solutions to the challenges since they are getting more and more complex.

Description

This challenge is about creating a Tic Tac Toe game in typescript type system.
For this we are working with some simple primitives types to describe the game.

The game

type TicTacToeChip = '❌' | '⭕';
type TicTacToeEndState = '❌ Won' | '⭕ Won' | 'Draw';
type TicTacToeState = TicTacToeChip | TicTacToeEndState;
type TicTacToeEmptyCell = '  ';
type TicTacToeCell = TicTacToeChip | TicTacToeEmptyCell;

type TicTactToeBoard = TicTacToeCell[][];

type TicTacToeGame = {
  board: TicTactToeBoard;
  state: TicTacToeState;
};

The game is played on a 3x3 board, each player has a chip, the first player has the ❌ chip and the second player has the ⭕ chip.
The game is won when a player has 3 chips in a row, column or diagonal.
The game is a draw when the board is full and no player has won.

The Game is represented by a TicTacToeGame object, which has a board Matrix and a state.

The board is a 3x3 matrix of TicTacToeCell which can be either a TicTacToeChip or a TicTacToeEmptyCell.

The challenge

Playing the game is done by calling the TicTacToe Utility type with the current game state and the next move.
The utility type will return the next game board and state.

Example

  Expect<
    Equal<
      TicTacToe<NewGame, 'top-center'>,
      {
        board: [
          [ '  ', '❌', '  ' ],
          [ '  ', '  ', '  ' ],
          [ '  ', '  ', '  ' ]
        ];
        state: '⭕';
      }
    >
  >

Solution to place a chip on the board

Here we will follow a step by step approach to solve this challenge.

Step 1: Map move to board position

The board can be described as a 3x3 matrix of TicTacToeCell.
Row and column are 0 based index, starting from the top left corner.

Here a mapping of the board position to the row and column index, keeping the index as string. This will come in handy later.

type PositionMap = {
  'top-left': ['0', '0'];
  'top-center': ['0', '1'];
  'top-right': ['0', '2'];
  'middle-left': ['1', '0'];
  'middle-center': ['1', '1'];
  'middle-right': ['1', '2'];
  'bottom-left': ['2', '0'];
  'bottom-center': ['2', '1'];
  'bottom-right': ['2', '2'];
};

Step 2: Set the chip on the board

Now that we have a mapping of the board position to the row and column index, we can set the chip on the board using Object Mapping.
Indeed we learned in previous challenges that we can use the Object Mapping to do a For Loop on Tuples.

We can divide the problem in 2 parts:

Set the chip on the row
Set the row on the board

We are also carreful to not override an existing chip on the board.
In such case we keep the existing board state.

Notice that we use K extends index to only set the chip on the row index. K is a string, that's why the mapping is done with string index.

type PlaceChipOnTuple<
  T extends TicTacToeCell[],
  X,
  Chip extends TicTacToeChip
> = {
  [K in keyof T]: K extends X ? 
    T[K] extends '  ' ?  // set only if the cell is empty
      Chip : 
      T[K] : 
    T[K];
};

type PlaceChipOnMatrix<
  Board extends TicTactToeBoard,
  Position extends [string, string],
  Chip extends TicTacToeChip,
  $y = Position[0], // alias for row index
  $x = Position[1]  // alias for column index
> = {
  [K in keyof Board]: K extends $y
    ? PlaceChipOnTuple<Board[K], $x, Chip>
    : Board[K];
};

We are not done yet, we can create a utility type to set the chip on the board given the current state. If the state is a win or a draw, we keep the current board.

Notice a trick here, we use Extract to cast the result to TicTactToeBoard since typescript has a hard time to infer the type.

type PlaceChip<
  Board extends TicTactToeBoard,
  Position extends [string, string],
  State extends TicTacToeState
> = State extends TicTacToeChip
  ? Extract<PlaceChipOnMatrix<Board, Position, State>, TicTactToeBoard>
  : Board;

Solution to check if the game is won

Now that we can place a chip on the board, we can check if the game is won.
For this we need to check if we have 3 same chips is in a row, column or diagonal.

Step 1: Check if rows are won

Enabler

We can check if a row is won by checking if all the chips in the row are the same.
We create a utility type to check if a row is won, given a Tuple.
This will come in handy for other checks.

type CheckCells<T extends TicTacToeCell[]> = 
  T extends [infer A, ...infer B]
  ? B[number] extends A
    ? A extends '  '
      ? false
      : A
    : false
  : false;

here we check that the first cell is the same as the rest of the cells in the row. We also check that the first cell is not empty to be sure that it's a Chip.
Note that we return the Chip if the row is won, this will come in handy later.

Check one row

So to check if a row is won, we can use the CheckCells utility type on the Board

type CheckRow<Board extends TicTactToeBoard, Row extends number> = 
  CheckCells<Board[Row]>;

Check all rows

Here we use a trick to check all the rows, we use typescript Distributive Conditional Types to iterate over the rows.

type CheckRows<
  Board extends TicTactToeBoard,
  $iter extends number = 0 | 1 | 2
> = $iter extends number
  ? CheckRow<Board, $iter> extends infer Chip extends TicTacToeChip
    ? Chip
    : never
  : never;

Step 2: Check if columns are won

Check one column

We can reuse the CheckCells utility type to check if a column is won.

type CheckColumn<
  Board extends TicTactToeBoard,
  Column extends number
> = CheckCells<[Board[0][Column], Board[1][Column], Board[2][Column]]>;

Check all columns

It's the same as rows now :

type CheckColumns<
  Board extends TicTactToeBoard,
  $iter extends number = 0 | 1 | 2
> = $iter extends number
  ? CheckColumn<Board, $iter> extends infer Chip extends TicTacToeChip
    ? Chip
    : never
  : never;

Step 3: Check if a diagonal is won

Enabler

We can reuse the CheckCells utility type to check if a diagonal is won.
But first we create a Map to get the diagonal cells from the board.

type DiagonalMap = [
  [[0, 0], [1, 1], [2, 2]], 
  [[0, 2], [1, 1], [2, 0]]
];

Check one diagonal

Now we can use the DiagonalMap to get the diagonal cells from the board and check if the diagonal is won.

type CheckDiagonal<
  Board extends TicTactToeBoard,
  N extends number
> = CheckCells<
  [
    Board[DiagonalMap[N][0][0]][DiagonalMap[N][0][1]],
    Board[DiagonalMap[N][1][0]][DiagonalMap[N][1][1]],
    Board[DiagonalMap[N][2][0]][DiagonalMap[N][2][1]]
  ]
>;

Check all diagonals

It's the same as rows and columns now :

type CheckDiagonals<
  Board extends TicTactToeBoard,
  $iter extends number = 0 | 1
> = $iter extends number
  ? CheckDiagonal<Board, $iter> extends infer Chip extends TicTacToeChip
    ? Chip
    : never
  : never;

Step 4: Check if the game is won

We can combine the previous checks to check if the game is won by using all the checks in a union.

type Winner<Board extends TicTactToeBoard> = CheckRows<Board> | CheckColumns<Board> | CheckDiagonals<Board>;

Step 5: Check if the game is a draw

checking if the game is a draw is simple, we just check if the board is full. And it's full if there is no empty cell.

type CheckFilled<Board extends TicTactToeBoard> =
  '  ' extends Board[number][number] ? false : true;

Implementing the TicTacToe Utility type

Step 1: Next game state

Now that we have all the utilities to check if the game is won or a draw, we can implement a GameNextState utility type, so that after a move we can check if the game is won or a draw.

type NextGameState<
  Board extends TicTactToeBoard,
  State extends TicTacToeState,
  $winner = Winner<Board>
> = [$winner] extends [never]
  ? CheckFilled<Board> extends false
    ? State extends '❌'
      ? '⭕'
      : '❌'
    : 'Draw'
  : `${$winner & string} Won`;

Step 2: Implement the TicTacToe Utility type

Now that we have all the utilities to place a chip on the board and check if the game is won or a draw, we can implement the TicTacToe utility type.

Notice 1 that we use PositionMap[Position] to get the row and column index from the position.
Notice 2 that we use PlaceChip to place the chip on the board.
Notice 3 that we use NextGameState to get the next game state.

And we use $ default variables to simplify the logic.

type TicTacToe<
  Game extends TicTacToeGame,
  Position extends TicTacToePositions,
  $Position extends [string, string] = PositionMap[Position],
  $nextBoard extends TicTactToeBoard = PlaceChip<
    Game['board'],
    $Position,
    Game['state']
  >
> = {
  board: $nextBoard;
  state: $nextBoard extends Game['board']
    ? Game['state']
    : NextGameState<$nextBoard, Game['state']>;
};

Conclusion

We have seen how to create a Tic Tac Toe game in typescript type system.
We have seen how to use Object Mapping to iterate over Tuples.
We have seen how to use Distributive Conditional Types to iterate over a range of numbers.
We have seen how to use Extract to cast a type.
We have seen how to use $ default variables to simplify the logic.

You can check the full solution on TS Playground.

Hope you enjoyed this challenge, see you next time.

Write typesafe APIs with zodios

ecyrbe — Sun, 18 Sep 2022 06:36:48 +0000

Writing client APIs, that gives you autocompletion is time consuming. You allways endup writing the same kind of boilerplate code or have to use openapi code generators that are a pain to maintain.

Zodios was created to make creating frontend (and optionally backend) API client a breeze.
It's is an open source REST API toolbox with end-to-end typesafety.
It allows you to create a REST API with a clean, intuitive and declarative syntax.
It's best used with TypeScript, but it's also usable with pure JavaScript.

Declaring returned data with zod

You can predefine some schemas to reuse them in your API definition. Zodios will use these definition to make runtime checks. Your API client is then typesafe at runtime.

import { Zodios, asErrors } from "@zodios/core";
import z from "zod";

const errors = asErrors([
  {
    status: "default",
    schema: z.object({
      error: z.object({
        code: z.number(),
        message: z.string(),
      }),
    }),
  },
]);

const user = z.object({
  id: z.number(),
  name: z.string(),
  age: z.number().positive(),
  email: z.string().email(),
});

Declaring your API endpoints

Then you can define your API endpoints directly in the Zodios constructor.

const apiClient = new Zodios('/api', [
  {
    method: "get",
    path: "/users",
    alias: "getUsers",
    parameters: [
      {
        name: "limit",
        type: "Query",
        schema: z.number().positive().default(10),
      },
      {
        name: "page",
        type: "Query",
        schema: z.number().positive().default(0),
      },
    ],
    response: z.object({
      nextPage: z.number(),
      users: z.array(user),
    }),
  },
  {
    method: "get",
    path: "/users/:id",
    alias: "getUser",
    response: user,
    errors,
  },
  {
    method: "post",
    path: "/users",
    alias: "createUser",
    parameters: [
      {
        name: "user",
        type: "Body",
        schema: user.omit({ id: true }),
      },
    ],
    response: user,
    errors,
  },  
]);

Calling your APIs

And finally you can use it to fetch data from your API.

// get all users
const users = await apiClient.getUsers();
// get user by id
const user = await apiClient.getUser({ params: { id: 1 } });
// create user
const newUser = await apiCLient.createUser({ name: "John", age: 20, email: "jodn@doe.com"});

Using Zodios with React

Zodios provides you react hooks based on react-query. Zodios manages your query keys, for you, no need to handle them by hand.

const zodiosHooks = new ZodiosHooks("myAPI", apiClient);

const Users = () => {
  const {
    data: users,
    isLoading,
    error,
    fetchNextPage,
    invalidate: invalidateUsers, // zodios also provides invalidation helpers
  } = zodiosHooks.useInfiniteQuery(
    "/users",
    { queries: { limit: 10 } },
    {
      getPageParamList: () => {
        return ["page"];
      },
      getNextPageParam: () => {
        return {
          queries: {
            page: page.nextPage + 1,
          },
        };
      },
    }
  );
  const { mutate } = zodiosHooks.useCreateUser(undefined, {
    onSuccess: () => invalidateUsers(),
  });

  return (
    <>
      <h1>Users</h1>
      <button onClick={() => mutate({ name: "john doe" })}>add user</button>
      {isLoading && <div>Loading...</div>}
      {error && <div>Error: {(error as Error).message}</div>}
      {users && (
        <>
          <ul>
            {users.pages.flatMap((page) =>
              page.map((user) => <li key={user.id}>{user.name}</li>)
            )}
          </ul>
          <button onClick={() => fetchNextPage()}>more</button>
        </>
      )}
    </>
  );
};

What's next

Zodios has much more tools under the hood.
API client has a powerfull plugin system.
Zodios also provides an 'express' adapter, so you can also create your server APIs safely with nodeJS.
It integrates also nicely with 'NextJS'.

Take a look a zodios website

How to test your typescript utility types

ecyrbe — Sun, 19 Jun 2022 20:08:14 +0000

Typescript has some nice utility types to help you improve code typing.

As a reminder, utility types, are like functions but for types. What this means is that utility types take types as parameters and return types as output.

For example the utility named Parameters<T> is defined like this :

type Parameters<T extends (...args: any) => any> = 
     T extends (...args: infer P) => any ? P : never;

It takes any function type as a parameter and returns a Tuple of all the function parameters.

Sometimes you need to create your own custom utility types.

And if usually you add some unit tests for your functions, you might also want to do the same for your utility type.

But how to test them ? Does this mean that tests are run at compile time and fail to report errors at runtime ? can you do these tests with your favorite test Runner ?

Utility to compare two types

First of all, if you want to test your utility types, at the minimum we will need to compare the output of your utility type to the expected one.

First try

One could try to do this :

type Equals<T,U> = T extends U ? U extends T ? true : false : false;

This will work until you realise that this returns true :

type Test = Equals< 1, 1 | 2 >;

This is due to how typescript conditional types work. It's doing distributive conditional typing.

Since we want to do strict type equality, we want to disable distributive behaviour.

Disabling distributive conditional typing

One way of doing it is to hide the type you want to test inside. For example, like this :

type Equals<T,U> = [T] extends [U] ? [U] extends [T]? true: false : false;

Now :

type Test = Equals< 1, 1 | 2 >;

returns false.

But we are not there yet. Indeed, because of any, this will return true :

type Test = Equals< any, 1 | 2 >;

Solution

type Equals<T, U> =
    (<V>() => V extends T ? 1 : 2) extends
    (<V>() => V extends U ? 1 : 2) ? true : false;

This solution relies on internal understanding of Typescript isTypeIdenticalTo. For a more detailed explanation, you can check this issue

How to use it to run your utility type tests

When writing tests, you need to have something to help you diagnose the issue, a readable message.

So you can write the previous test like this :

type Assert<T, U> =
    (<V>() => V extends T ? 1 : 2) extends
    (<V>() => V extends U ? 1 : 2) ? true : 
    { error: "Types are not equal"; type1: T; type2: U };

Now when Assert checks that two types are not equal, you'll get a nice message.

And you can use it like this :

const test1: Assert<Parameters<(a: number)=>void>,[number]> = true; // pass
const test2: Assert<Parameters<(a: number)=>void>,[string]> = true; // fail

Conclusion

By using this Assert utility type (you can even use it to test itself) you'll be able to add unit tests for your own utility types.

This will show you a nice message as to why it fails and where. It will allow you to monitor typescript regressions in the type system for your utility types.

if you want to see it in practice, you can check some tests here for zodios library.

If this article was helpfull to you, don't forget to give it a thumbsup.

How to use advanced Typescript to define a `pipe` function

ecyrbe — Sat, 11 Jun 2022 17:25:49 +0000

Typescript is awesome but some functionnal libraries have limited implementation for Typescript definitions of :

pipe
compose
flow

To remind you what these functions do, let take an example. Imagine you want to chain multiple functions calls :

const n = -19;
const result = Math.floor(Math.sqrt(Math.abs(n))));

This can be hard to read hence the pipe function :

const n = -19;
const result = pipe(n, Math.abs, Math.sqrt, Math.floor);

This is easier to read, because the read order is the same as the execution order. This becomes clearer as the number of composed functions grow.

The problem

But unfortunately that's where most libraries have issues. Ideed, if you look closely at fp-ts or lodash pipe implementations you'll see that typescript support has a limited function count support.

For fp-ts, after 19 composed functions, you'll have no more type checking.
For lodash, it's even worse, only 9 functions are supported.
This is because these libraries are using Typescript function overload definition instead of recursive Typescript definitions.

So here we'll take a look at some advanced Typescript to define unlimited function parameters for pipe definition.

Javascript pipe implementation

First we are implementing a version of the pipe function without type annotations :

function pipe(arg, firstFn, ...fns) {
  return fns.reduce((acc, fn) => fn(acc), firstFn(arg));
}

It's pretty simple. An alternative for loop implementation would be :

function pipe(arg, firstFn, ...fns) {
  let result = firstFn(arg);
  for (let fn of fns) {
    result = fn(result);
  }
  return result;
}

How is pipe function constrained ?

When we say we want to add Typescript definition it's because if one of the functions result don't match the next function parameter type, we are likely to encounter a runtime error.
And it would be nice to catch this error at compile time, so the programmer knows early that there is a type missmatch.

To illustrate the constraints of the pipe function parameters, we can take the fp-ts implementation for 2 functions:

function pipe<A, B, C>(a: A, ab: (a: A) => B, bc: (b: B) => C): C

what we can observe is that :

The first function parameter type should match the first pipe parameter type
The result type of intermediary functions should match the parameter type of the next function
The result type of the last function is the result type of the pipe function

we'll now translate these contraint in Typescript.

Typescript pipe definition

Let's add types with the final function definition. Don't be affraid, we'll explain everything :

function pipe<FirstFn extends AnyFunc, F extends AnyFunc[]>(
  arg: Parameters<FirstFn>[0],
  firstFn: FirstFn,
  ...fns: PipeArgs<F> extends F ? F : PipeArgs<F>
): LastFnReturnType<F, ReturnType<FirstFn>> {
  return (fns as AnyFunc[]).reduce((acc, fn) => fn(acc), firstFn(arg));
}

This implementation is the same as the javascript one, but with some type annotations.

Let's decrypt everything :

first line

function pipe<FirstFn extends AnyFunc, F extends AnyFunc[]>(

This mean that pipe is a generic function with two generic parameters unknown when defining this function. But we know at least that all generic parameters should be functions. that's the meaning of FirstFn extends AnyFunc and F extends AnyFunc[].

And AsyncFn is defined as :

type AnyFunc = (...arg: any) => any;

first parameter

  arg: Parameters<FirstFn>[0],

Typescript comes with some utility type. Here we are using Parameters that extracts all parameters from the supplied function.
Here we only care about the first parameter of the first function passed as parameter, hence the [0] type array access.
This first arg is validating our first constraint :

The first function parameter type should match the first pipe parameter type

second parameter

This one is pretty straightforward. It's the first function passed to the pipe one.

rest of the parameters

  ...fns: PipeArgs<F> extends F ? F : PipeArgs<F>

So here is the real deal. What is PipeArgs ? why not just telling Typescript that fns is of type F?

This is where we are applying our second constraint :

The result type of intermediary functions should match the parameter type of the next function

PipeArgs definition :

type PipeArgs<F extends AnyFunc[], Acc extends AnyFunc[] = []> = F extends [
  (...args: infer A) => infer B
]
  ? [...Acc, (...args: A) => B]
  : F extends [(...args: infer A) => any, ...infer Tail]
  ? Tail extends [(arg: infer B) => any, ...any[]]
    ? PipeArgs<Tail, [...Acc, (...args: A) => B]>
    : Acc
  : Acc;

So PipeArgs is running through all function parameters and returning a new type with function definition where the return type of a function is the first parameter of the next function. It's a recursive type definition, and we are using Typescript Tail recursive optimization to be allowed to have around 1000 possible functions passed as pipe parameters.

For example, if we have this type definition (invalid pipe arguments since D is not of type B :

type Input<A,B,C,D> = [(a: A) => D, (b: B) => C]

then we have in output :

type Output<A,B,C,D> = PipeArgs<Input<A,B,C,D>>
// Output is [(a: A) => B, (b: B) => C]

The first function is now a valid pipe parameter, since we satisfy our second constraint.

Now all we have to do is check if this PipeArgs<F> is equal to F.

If so, we have a valid definition. Else it's invalid. If it's invalid we return the valid definition so Typescript will point exactly where is the error.

That's what this does :

  ...fns: PipeArgs<F> extends F ? F : PipeArgs<F>

result type constraint

): LastFnReturnType<F, ReturnType<FirstFn>> {

And we are getting back the last function return type
and if it's not defined we use ReturnType utility type to return the first function result type.

Here is the definition of LastFnReturnType by using Typescript leading spread operator to match the last function :

type LastFnReturnType<F extends Array<AnyFunc>, Else = never> = F extends [
  ...any[],
  (...arg: any) => infer R
] ? R : Else;

Conclusion

This is advanced Typescript for library authors. By adding this kind of type definition you can improve your type definitions for advanced functionnal code.

I'd like to emphasize that Typescript type system is Turing complete, so if you think some advanced typing is impossible to do with Typescript, you should think twice.

Because chances are that you can. It might not be easy and i hope Typescript will improve on this part.

For those that want to check the whole code, it's here on the playground

If you this article was helpfull to you, don't forget to add a thumbs up.

Zodios : an open source HTTP client with type checking at both compile time and runtime (part 2/3)

ecyrbe — Tue, 24 May 2022 11:40:10 +0000

In the last article we have seen how to use zodios to declare custom REST APIs.

As a reminder, Zodios is an open source HTTP client with type checking at runtime (zod validation) and also at compile time (typescript) without needing to write both types and validation schemas.

You just need to write your API declaration once and you're done.

In this follow up, we will take a look at some features of Zodios that can make your life easier :

Alias endpoints
CRUD helper
React hooks

Alias endpoints

When using previous versions of zodios, you had no choice but to repeat yourself and write again your PATH both when declaring your API and when using it.

It's great for readability, but in some use cases, repeating it can be tedious.

Check this example from an issue a user sent :

const MY_ORG = 'my-org-id' as const; // user wanted to extract his organization ID from the declaration
const client = new Zodios(BASE_API_URL, [
  {
    method: 'get',
    path: `/v1/organizations/${MY_ORG}/shipments`,
    response: schipmentSchema
  }
] as const)

And then to call this API you should do :

const shipments = await client.get(`/v1/organizations/${MY_ORG}/shipments`);

Now with zodios you can declare aliases :

const MY_ORG = 'my-org-id' as const; // if your org changes you only need to change it once here
const client = new Zodios(BASE_API_URL, [
  {
    method: 'get',
    path: `/v1/organizations/${MY_ORG}/shipments`,
    alias: 'getOrgShipments',
    response: schipmentSchema
  }
] as const)

And then to use it :

const shipments = await client.getOrgShipments();

You no longer need to repeat yourself.

CRUD Helper

This feature might not suit all your needs, but if you have simple CRUD declarations, you can use asCrudApi() helper to not repeat yourself.

If you have more complex APIs, but your endpoints are standardized, you can create your own helper, take a look at asCrudApi() implementation for inspiration.

import { Zodios, asCrudApi } from '@zodios/core';

const userSchema = z.object({
  id: z.number(),
  name: z.string(),
});
const apiClient = new Zodios(BASE_URL, 
asCrudApi('user',userSchema));

This is esquivalent to this more verbose declaration :

const apiClient = new Zodios(BASE_URL, [
  {
    method: "get",
    path: "/users",
    alias: "getUsers",
    description: "Get all users",
    response: z.array(userSchema),
  },
  {
    method: "get",
    path: "/users/:id",
    alias: "getUser",
    description: "Get a user",
    response: userSchema,
  },
  {
    method: "post",
    path: "/users",
    alias: "createUser",
    description: "Create a user",
    parameters: [
      {
        name: "body",
        type: "Body",
        description: "The object to create",
        schema: userSchema.partial(),
      },
    ],
    response: userSchema,
  },
  {
    method: "put",
    path: "/users/:id",
    alias: "updateUser",
    description: "Update a user",
    parameters: [
      {
        name: "body",
        type: "Body",
        description: "The object to update",
        schema: userSchema,
      },
    ],
    response: userSchema,
  },
  {
    method: "patch",
    path: "/users/:id",
    alias: "patchUser",
    description: "Patch a user",
    parameters: [
      {
        name: "body",
        type: "Body",
        description: "The object to patch",
        schema: userSchema.partial(),
      },
    ],
    response: userSchema,
  },
  {
    method: "delete",
    path: "/users/:id",
    alias: "deleteUser",
    description: "Delete a user",
    response: userSchema,
  },
] as const);

You can also see, that aliases for all CRUD endpoints are autogenerated.
So you can call your endpoints with them :

const users = await client.getUsers();

React Hooks

Zodios also has some React Hooks. Behind the scene, Zodios is using react-query.

You can also use your alias for hooks. They will be automatically prefixed with use<Alias>.

For example, alias getUsers can be used with useGetUsers hook.

import React from "react";
import { Zodios } from "@zodios/core";
import { ZodiosHooks } from "@zodios/react";
import { z } from "zod";

const baseUrl = "https://jsonplaceholder.typicode.com";

const userSchema = z
  .object({
    id: z.number(),
    name: z.string(),
  });

const zodios = new Zodios(baseUrl, asCrudApi('user',userSchema));
const zodiosHooks = new ZodiosHooks("jsonplaceholder", zodios);

const Users = () => {
  const {
    data: users,
    isLoading,
    error,
    invalidate: invalidateUsers, // zodios also provides invalidation helpers
  } = zodiosHooks.useGetUsers();
  const { mutate } = zodiosHooks.useCreateUser(undefined, {
    onSuccess: () => invalidateUsers(),
  });

  return (
    <>
      <h1>Users</h1>
      <button onClick={() => mutate({ name: "john doe" })}>add user</button>
      {isLoading && <div>Loading...</div>}
      {error && <div>Error: {(error as Error).message}</div>}
      {users && (
        <ul>
          {users.map((user) => (
            <li key={user.id}>{user.name}</li>
          ))}
        </ul>
      )}
    </>
  );
};

Conlusion

That all for today. Zodios is still evolving. If you have use cases you'd like to see in Zodios, please, create an issue on github, or even better contribute with a Pull Request.

If you like zodios, don't forget to give this article a thumbs up.

Webpack Module Federation for production environnement

ecyrbe — Sat, 26 Feb 2022 11:31:24 +0000

Webpack Module federation is a really nice piece of technology for decoupling your micro frontends setups, with dynamic shared code resolution. All the pitfalls of webpack externals gone.

But i see a lot of problematic examples on how to setup ModuleFederation with toy setups that don't work for production environnement or even even worse, hacky solutions thats no one can understand without understanding webpack arkanes.
Here on dev.to, check this one. Even the tagged update with promise example from the MF author himself is a problematic setup.

It's problematic, because these setups are not Website URL agnostic or rely on runtime hacks to inject your integration / staging / production URLs. These setups don't scale even if they claim they do so.

Here i'm going to show a non problematic setup example, that do not need runtime hacks or configurations.

A simple configure once, build once, deploy everywhere setup.
Sounds like magic, doesn't it. Let's dive in.

Architecture

The first thing you should notice, is that everything is behind the same domain URL. So the fist recommendation of this setup is :

Put your website behind one and only one Domain URL.
- No CORS configuration nightmare.
- It hides your internal architecture from the end-user. your users should have no idea that your website is split into micro-frontends.
- It simplifies your webpack configuration with module federation.

To hide your internal architecture from the user, use a reverse Proxy. It can be any technology, like Nginx, Kong, HaProxy, kubernetes ingress, ...

From one domain to URL agnostic setup

How does this setup simplifies webpack configuration with module federation ?

Some of you might already know this. It's the same recommandation you have always been told as frontend developpers. So here is the second recommandation for this setup :

Use relavite path URLs for your own website URLs. Only use domain URLs for external websites.
- domain URL: https://domain/mfe-1
- relavite URL: /mfe-1

So, it's really that simple. Module Federation is webpack, and webpack supports relative URL setup.
By using relative URL, you won't need to configure your website Domain anywhere and you'll be able to deploy it everywhere. The same build, deployed on your integration, staging and production environnments.

Webpack example config for Host

So here is a webpack.config.js example for your Host using only only relative URL. No harcoded Domain. The important parts are in:

'publicPath' attribute that should use relative URL,
'remotes' property in ModuleFederation setup that should also use relative URL



const path = require('path');

const HtmlWebpackPlugin = require('html-webpack-plugin');

const { ModuleFederationPlugin } = require('webpack').container;

const deps = require('./package.json').dependencies;

const webpack = require('webpack');

module.exports = {

  mode: 'production',

  entry: '<path to your local host index.js>',

  cache: false,

  devtool: false,

  optimization: {

    minimize: true,

  },

  output: {

    // you could use 'auto', but 'auto' does not work with ie11, it's better to use relative url anyway.

    publicPath: '/',

    clean: true,

    pathinfo: false,

    path: buildPath,

  },

  resolve: {

    extensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],

  },

  module: {

    rules: [

      {

        test: /.css$/,

        use: ['style-loader', 'css-loader'],

      },

      {

        test: /.(js|jsx|ts|tsx)$/,

        exclude: /node_modules/,

        loader: 'swc-loader',

        options: {

          cacheDirectory: true,

        },

      },

    ],

  },

    : [

        new ModuleFederationPlugin({

          name: 'host',

          remotes: {

            // relative URL

            mfe_1: 'mfe_1@/mfe-1/remoteEntry.js',

            mfe_2: 'mfe_2@/mfe-2/remoteEntry.js',

          },

          shared: {

            ...deps,

          },

        }),

        new HtmlWebpackPlugin({

          template: 'index.html',

          inject: 'body',

          hash: true,

          minify: true,

        }),

      ],

};

Webpack example config for a micro-frontend

So here is a webpack.config.js example for your Micro-frontend using only only relative URL. No harcoded Domain. The important parts are in:

'publicPath' attribute that should use relative URL,



const path = require('path');

const HtmlWebpackPlugin = require('html-webpack-plugin');

const { ModuleFederationPlugin } = require('webpack').container;

const deps = require('./package.json').dependencies;

const webpack = require('webpack');

module.exports = {

  mode: 'production',

  entry: '<path to your local mfe index.js>',

  cache: false,

  devtool: false,

  optimization: {

    minimize: true,

  },

  output: {

    // relative URL

    publicPath: '/mfe-1/',

    clean: true,

    pathinfo: false,

    path: buildPath,

  },

  resolve: {

    extensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],

  },

  module: {

    rules: [

      {

        test: /.css$/,

        use: ['style-loader', 'css-loader'],

      },

      {

        test: /.(js|jsx|ts|tsx)$/,

        exclude: /node_modules/,

        loader: 'swc-loader',

        options: {

          cacheDirectory: true,

        },

      },

    ],

  },

  plugins: [

        new ModuleFederationPlugin({

          name: 'mfe_1',

          filename: 'remoteEntry.js',

          library: { type: 'var', name: 'mfe_1' },

          remotes: {},

          exposes: {

            './view1': '<path to your local view js>',

          },

          shared: {

            ...deps,

          },

        }),

      ]

};

Conclusion

You should not need to understand the arkanes of webpack to configure module federation for your production environnement.
Just remember these two rules :

Put your website behind one and only one Domain URL.
Use relavite path URLs for your own website URLs. Only use domain URLs for external websites.

Thanks for reading. Don't forget to like the article if it was usefull to you.

Zodios : an open source HTTP client with type checking at both compile time and runtime (part 1/3)

ecyrbe — Sun, 20 Feb 2022 00:23:25 +0000

You might be familiar zod. It's a schema validation library like many others, that allows you to validate data from user inputs or network request.

The bonus you get from zod compared with the other similar libraries is that it's made from the ground up to use typescript, so it's one of the best to infer your typescript types and not duplicate declarations.

Indeed, with other libraries, you might have to declare your types with typescript and your schema with your validation library.

With zod, you only have to do it once :

const user = z.object({
  id: z.number(),
  type_of: z.string(),
  name: z.string(),
  username: z.string(),
});
type User = = z.infer<typeof user>;
/* same as */
type User = {
  id: number;
  type_of: string;
  name: string;
  username: string;
};

Zodios

Zodios is a small open-source library that helps you declare your REST APIs in frontend applications thanks to Zod library.

You might be wondering why would you use another library since you might already be using fetch or axios to make your api requests.

Indeed, both allow you to make your API calls. But maybe some of you are experiencing the same issues all the time. You might need to :

Validate your API results and have to write both your types and schemas,
Have autocompletion and end-up using client api code generators like swagger editor client generator.

Zodios was made to address both these uses cases without having to rely on third party code generators that might produce unmaintainable code.

A basic example :

Before diving into more complex example in the second part of this article, here is a simple one.

We want to call the excellent jsonplaholder service to get all it's users and be able to filter the result with raw text search.

The endpoint we want to call : https://jsonplaceholder.typicode.com/users?q=ell
And here is how you would declare everything with zodios :

const apiClient = new Zodios(
  "https://jsonplaceholder.typicode.com",
  // API definition
  [
    {
      method: "get",
      path: "/users",
      description: "Get all users",
      parameters: [
        {
          name: "q",
          description: "full text search in users",
          type: "Query",
          schema: z.string(),
        },
      ],
      response: z.object({
        id: z.number(),
        name: z.string(),
        email: z.string(),
        address: z.object({
          street: z.string(),
          suite: z.string(),
          city: z.string(),
          zipcode: z.string(),
          geo: z.object({
            lat: z.string(),
            lng: z.string()
          }),
      }),
    },
  ] as const,
);
const users = await apiClient.get("/users", { queries: { q: "ell" } });
console.log(users);

We see that we created a new instance of Zodios and we provided to it:

the base URL of jsonplaceholder
a user API declaration with something looking a lot like a schema or model declaration, but instead of using openapi json schema, we used zod syntax.

We then called this instance like we almost would with axios.
But what Zodios gives you with this schema declaration, is autocompletion and types with typescript out of the box.

Indeed, if you hover your mouse over the users variable in your typescript IDE, you'll get this :

const users: {
  id: string;
  name: string;
  email: string;
  address: {
    street: string;
    suite: string;
    city: string;
    zipcode: string;
    geo: {
      lat: string;
      lng: string;
    };
  };
}[]

Your IDE just infered the types based on Zodios API declaration.

You'll also get autocompletions for all the parameters of the API telling you to provide in queries the q : string property.

Behind the scene, zodios is using Zod type inference and some custom typescript utility types.

Conclusion

Like many tools, this solution might not please everyone needs. Some might still prefer code generation tools to handle client API generation.

Zodios has the advantage of letting you in control with minimum boilerplate.

In the next articles, we will see :

How to declare alias endpoints
How to declare CRUD endpoints easily
How to handle large APIs declarations (like the one of dev.to).
How to split zod declarations and API declarations into multiple files.

You can see the example we'll talk about here

How to create your own private cloud : part 1

ecyrbe — Tue, 03 Aug 2021 01:15:39 +0000

Hello folks,

Have you ever wondered how do cloud providers build their cloud ? How do circle-ci, github actions, gitlab-ci do run your tests and builds your projects in their cloud ?

Don't wonder anymore, because in this series, i'll show to build your own mini-cloud at home.

Disclaimer:

it will require some hardware investment,
it will give you a glimpse of hardware architecture, but not full picture (we will not cover spine/leaf nodes architecture used in cloud datacenters)

What hardware do you need ?

At least two raspberry pi with 4GB each (official price 55$ each),
One MicroSD card for each Raspberry pi (i recommend taking at least a 32GB card),
[optional] A Raspberry pi POE+ hat for each Raspberry pi (official price 20$ each)
[optional] A POE+ ethernet switch (or the official raspberry pi power supply if you can't afford a POE switch and want to use wifi for networking)
[Optional] A cluster case for a clean setup.

I made one based on 4 Raspberry pi's with POE+ hat and a POE+ switch. Total Budget : 400$.

If you go with only two RPI's over WIFI, it will cost you around 150$.

What it looks like?

night mode

day mode

Install Ubuntu server ARM64 on SD card

We could install the official Raspberry pi OS on each card, but unfortunately, raspberry only support 32 bit images officially (their 64 bit OS is still broken from time to time), and we want to use the full power of Raspberry pi 4 which is 64 bit. See this benchmark to compare for yourself the huge difference :

So here i'll recommend using Ubuntu Server 20.04 LTS ARM64 build provided by Raspberry pi Imager.

Select Other general purpose OS>Ubuntu> Ubuntu server 20.04 LTS

And click on the Write button.

SD Card Modification

Before putting your SD card on your raspberry pi, you first need to make a few changes to allow you to use it in Headless mode (ie: without a screen and keyboard linked to it).

With your SD card still inserted, you should see two new disks :

bootfs
writable

Enable SSH

Still at the root of bootfs disk, create an empty file named ssh :

touch ssh

This will enable ssh connections on your Raspberry pi.

Enable container cpu and memory isolation

Open a Terminal and go to the bootfs filesystem of your SD Card, and open the cmdline.txt file.
You should see a single line, append this at the end of the line :

cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory

This will enable you to use kubernetes (k3s to be precise) on your cluster.

Optional Enable POE+ hat driver

Open userconfig.txt and append these lines at the end of the file :

dtoverlay=rpi-poe
dtparam=poe_fan_temp0=45000
dtparam=poe_fan_temp1=55000
dtparam=poe_fan_temp2=65000
dtparam=poe_fan_temp3=75000

This will enable POE+ hat driver and fan configuration to cool down your Raspberry pi.

Rename your Rasberrys

Now go to the writable disk and edit as an admin the etc/hosts and append at the end:

127.0.1.1 <your-new-name>

For the first SD card, i suggest naming it to recognize that's it will be the master node of your cluster. Mine is called k3s-main. For the other ones, you can choose a predictable name like k3s-worker-01 ...

Also edit etc/hostname and change the current name (ubuntu) to the name you just choose.

Insert your SD card and boot

Now you can insert your SD card in your Raspberry pi's. put power on and let them boot.

Connect to each of them with ssh

Now you need to connect to each of your booted Raspberry pi's. If you have wifi and a dhcp server, you might be able to connect to them using their name with .local appended to it. For exemple :

> ssh ubuntu@k3s-main.local

When prompted for password, just use ubuntu. it will ask you to change the default password after a successfull login.
Once the password changed, it will disconnect you.

If it does not work, don't worry. First run ifconfig to get information about your network.

> ifconfig
etho0: flags=4099<UP,BROADCAST,MULTICAST>  mtu 1500
        inet <YOUR.LOCAL.IP>  netmask 255.255.0.0  broadcast 172.19.255.255
        ether <MAC:ADDRESS>  txqueuelen 0  (Ethernet)
        RX packets 0  bytes 0 (0.0 B)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 0  bytes 0 (0.0 B)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

This should give you your local IP. replace the last two digits by 00 and run nmap :

> nmap -sn <YOUR.LOCAL.IP.ZERO>/24

This should return your your IP, plus the one of your Raspberry pi's. you should now be able to login using ssh and the raspberry IP

> ssh ubuntu@<Rasbpberry.IP>

If you have already setup a ssh key, i recommand using it to automatically connect to your Raspberry pi's without password prompt. To do this :

> ssh-copy-id -i ~/.ssh/id_rsa.pub ubuntu@k3s-main.local

Enter password for the last time when prompted.

Update your Raspberry pi's

On each Raspberry pi's within the SSH session, run :

> sudo apt update & sudo apt upgrade

Install k3s

Main node

On your main node (k3s-main for me), run the following command :

> curl -sfL https://get.k3s.io | sh -s - --write-kubeconfig-mode 644

Once the script finished execution, you should be able to see your node running :

> kubectl get nodes
NAME      STATUS    ROLES     AGE     VERSION
k3s-main   Ready    control-plane,master    1m      v1.21.0

Save your cluster token

save your token to allow your workers to join the main node

> cat /var/lib/rancher/k3s/server/node-token
<YOUR-TOKEN>

Join main node on workers

On each of your worker nodes (k3s-worker-01, k3s-worker-02, k3s-worker-03 for me) join the main node by running the following command :

> curl -sfL https://get.k3s.io | K3S_URL=https://k3s-main.local:6443 K3S_TOKEN=<YOUR-TOKEN> sh -

Once the scripts finished execution, you should be able to see your nodes running (execute on main node):

> kubectl get nodes
NAME      STATUS    ROLES     AGE     VERSION
k3s-main   Ready    control-plane,master    15m      v1.21.0
k3s-worker-01   Ready     <none>    3m      v1.21.0
k3s-worker-02   Ready     <none>    2m      v1.21.0
k3s-worker-03   Ready     <none>    1m      v1.21.0

Conclusion

So we have installed a cluster on raspberry pi's. what now ?

Next time, we'll see how to install rancher on your cluster to monitor and administrate it with a beautifull UI.

Just for fun : transform a simple code into over engineered functional style code (featuring javascript)

ecyrbe — Fri, 07 Aug 2020 20:41:26 +0000

Hi fellow programmers,

This article is kind of a nice (maybe) and pretty (i hope) exercise. But don't take it too seriously, no need to go into flamewars, take it as a fun exercise i did. Initially i wrote this as a comment in reaction to an article here that was deleted by it's author.
As a disclaimer, i love functional programming, object oriented programming, all kind of styles. They all have their pros/cons and beauty.

So let's begin and and imagine you have a beginner programmer writing this piece of code in javascript:

function daysUntil(day, month) {
  const today = new Date();
  const sameYear = new Date(today.getFullYear(), month - 1, day);
  if (sameYear > today)
    return Math.ceil((sameYear - today) / (1000 * 60 * 60 * 24));
  else {
    const nextYear = new Date(today.getFullYear() + 1, month - 1, day);
    return Math.ceil((nextYear - today) / (1000 * 60 * 60 * 24));
  }
}
console.log(daysUntil(1, 12));

Imagine you are this guy, doing this code maintenance :

Of course the first thing you see when taking ownership of the code is side effects (horror!). So let's quickly fix that mistake :

function daysUntil(day, month, today) {
  const sameYear = new Date(today.getFullYear(), month - 1, day);
  if (sameYear > today)
    return Math.ceil((sameYear - today) / (1000 * 60 * 60 * 24));
  else {
    const nextYear = new Date(today.getFullYear() + 1, month - 1, day);
    return Math.ceil((nextYear - today) / (1000 * 60 * 60 * 24));
  }
}
const today = new Date(); // side effect
console.log(daysUntil(1, 12,today));

Better. Now we can start coding. Because, yes, we got rid of the side effect but come on, this code is not declarative enough. As a functional programming adept, i have to transform the code above into something as simple as this :

// fn(number,number) -> fn(date) -> number
const daysUntil = (day, month) => daysBetween(now, futureDateFrom(day, month));

const today = new Date(); // side effect
console.log(daysUntil(1, 12)(today));

I can read this code and understand what it does, because it reads like a book. I want the days between now and the first December. As simple as that.

So we all heard of, divide and conquer in programming and that's what we are aiming for. So we have in our dreams, a function called futureDateFrom :

// fn(number,number) -> fn(date) -> date
const futureDateFrom = (day, month) => minUpperDate(sameYearOf(day, month), nextYearOf(day, month));

What does futureDateFrom do? It computes the first date in the future given a day and a month. It's a high order function, meaning it's a function that returns a function, and we create this function by composing multiple functions together.

And then we have another function called daysBetween:

// fn( fn(date)->date, fn(date)->date ) -> fn(date) -> number
const daysBetween = (getDateA, getDateB) => (date) =>
  Math.ceil(Math.abs(getDateA(date) - getDateB(date)) / (1000 * 60 * 60 * 24));

It takes two function that take a date and return a date as parameters and return a function that take a date and computes the days between those dates.
We now see that now is a function :

// fn(any) -> any
const now = (x) => x;

And it's the identity function, that returns whatever you give it as a parameter.

The rest of the functions are the following ones, and are simpler to understand, but still high order functions

// fn( fn(date)->date, fn(date)->date ) -> fn(date) -> date
const minUpperDate = (getDateA, getDateB) => (date) =>
  minUpperValue(getDateA(date), getDateB(date))(date);
// fn(number,number) -> fn(date) -> date
const sameYearOf = (day, month) => (date) => dateFrom(day, month, year(date));
// fn(number,number) -> fn(date) -> date
const nextYearOf = (day, month) => (date) => dateFrom(day, month, year(date) + 1);

we see that the missing functions can be implemented like so :

// fn(comparable, comparable) -> fn(comparable) -> comparable
const minUpperValue = (a, b) => (pivot) => (a < pivot && pivot < b ? b : a);
// fn(date) -> date
const year = (date) => date.getFullYear();
// fn(number, number, number) -> date
const dateFrom = (day, month, year) => new Date(year, month - 1, day);

And it's finished. We defined all the functions. We see that we managed to turn a single function into 10 simpler ones. These function have the benefit of being reuseable independant bits of code. All these function can now be unit tested easily.
But it's undeniable that the produced code is harder to read for the non initiated.

Do i think that writing all this code is worth it? Divide and conquer always have proved to make things easier to grasp and test but at the cost of complexity.

So you have to get a feeling at when to stop dividing your code, because it can be a never ending task that is not worth it. And in my experience, it stops being worth it when the divided code is not reused or if the code you want to split can be understood by itself. So as a rule of thumb, always ask yourself if the code you are splitting will be reused or is complex enough to be splitted.

As an exercise, we let you imagine you are in the shoes of this guy and write in Object oriented style an over engineered piece of code :