Category: bingo

Bingo

It was a nice journey  to make an application just with TypeScript and Node ecosystem.  There are some missing parts ( e.g. testing the GUI – e2e in JS parlance)

However, some thoughts:

1. The ecosystem does not have good support for mono-repository (in C# parlance , solution with multiple referencing projects )
   • Yarn Workspaces helps
   • TypeScript compile should be configured
2. The fact that you wrote once time the definitions is overrated
   • Still some different models for Web API and Console and Web should exists, if you are a purinst ( no swagger reference for console …)
   • The possibilities of mistake  because of the same  model are not trivial
3. Some tools require better documentation
   1. Finding how in nest return an HTML file is …. gard
   2. The errors are not so self explanatory ( for example, referencing i n warn workspaces something without his references)
4. Docker really helps to have repeatable builds
   1. CLI is your best friend –  programming and devops
   2. Docker copying results files are perfect
5. In our days, to be a full cycle programmer is easy with open source and stacks for open source( GitHub, AzureDevOps, Heroku, others)

Bingo

We have already documented the process of reproducing our code on developer PC ( including docker …)  So now we should help programmers understand the code that we have create and it’s general use.

For this, for any project that we have :

1. We should  add a Readme.md file to explain the project

2. We should add documentation for any class

3. We should generate the documentation for any class in a readable form ( preferably html)

3. We should deploy somewhere the documentation

For the first point, this is very easy ( although painful to write ). However, we should add a link to the 4th point , the link to the documentation.

For point 2 and 3 (adding documentation for any class and generating html ), we could use https://typedoc.org/  .

And ,because we are used to docker, I created build_code_documentation.txt docker file that runs typedoc on every project

FROM node:10
WORKDIR /app
WORKDIR /app
COPY package.json ./package.json
COPY bingo-cards-api/package.json ./bingo-cards-api/package.json
COPY bingo-cards-api-objects/package.json ./bingo-cards-api-objects/package.json
COPY bingo-cards-ui/package.json ./bingo-cards-ui/package.json
COPY bingo-meeting-console/package.json ./bingo-meeting-console/package.json
COPY bingo-meeting-objects/package.json ./bingo-meeting-objects/package.json
COPY bingo-meeting-objects-test/package.json ./bingo-meeting-objects-test/package.json
COPY yarn.lock ./yarn.lock

RUN yarn install

COPY . ./

RUN npm install –global typedoc
RUN yarn build
RUN typedoc –mode file –out docs/source/bingo-cards-api –ignoreCompilerErrors  –excludePrivate –excludeProtected bingo-cards-api/src
RUN typedoc –mode file –out docs/source/bingo-cards-api-objects –ignoreCompilerErrors  –excludePrivate –excludeProtected bingo-cards-api-objects/src
RUN typedoc –mode file –out docs/source/bingo-cards-ui –ignoreCompilerErrors  –excludePrivate –excludeProtected bingo-cards-ui/src
RUN typedoc –mode file –out docs/source/bingo-meeting-console –ignoreCompilerErrors  –excludePrivate –excludeProtected bingo-meeting-console
RUN typedoc –mode file –out docs/source/bingo-meeting-objects –ignoreCompilerErrors  –excludePrivate –excludeProtected bingo-meeting-objects
RUN typedoc –mode file –out docs/source/bingo-meeting-objects-test –ignoreCompilerErrors  –excludePrivate –excludeProtected bingo-meeting-objects-test

CMD tail -f /dev/null

And the bat file just copy on hard disj

docker build .. -f docker_build_code_documentation.txt -t bingo_build_code_documentation
docker run -d –rm –name bingo_build_code_documentation_container bingo_build_code_documentation
docker cp bingo_build_code_documentation_container:/app/docs/source .
docker container kill bingo_build_code_documentation_container

For the last point, we can deploy documentation at github pages , in a separate folder in docs, named source ( we will just copy the files genetated by docker)

You can find the result of the documentation at

bingo-cards-api

bingo-cards-api-objects

bingo-cards-ui

bingo-meeting-console

bingo-meeting-objects

bingo-meeting-objects-test

Bingo

Now we must code the endpoint to create a meeting. As per the nest.js documentation , we should create a module ,a controller and a service to redirect calls . The problem is that , to create a meeting, we should transmit 2 parameters: userName and meetingName. To do this via  HTTP, we must create a new class with this 2 parameters :

export class CreateMeeting {
  readonly userName: string;
  readonly meetingName: string;
}

Also we want to add Swagger as show at https://docs.nestjs.com/recipes/swagger .  And for this, according to the documentation , we should decorate the class:

import { ApiModelProperty } from '@nestjs/swagger';

export class CreateMeeting {
  @ApiModelProperty()
  readonly userName: string;
  @ApiModelProperty()
  readonly meetingName: string;
}

And now we have a controller with 2 functions – get – to show all meetings – and post-  to create the meeting:

@Controller('meetings')
export class MeetingsController {
    constructor(private meetingsService: MeetingService){}

    @Get()
    index(): Meeting[] {
      return this.meetingsService.meetings;
    }

    @Post()
    async create(@Body() cm: CreateMeeting): Promise<Meeting> {
        console.log(`userName : ${JSON.stringify(cm.userName)}  meetingName: ${JSON.stringify(cm.meetingName)}`);
        return this.meetingsService.create(cm.userName, cm.meetingName);

    }
}

And now we have a fully qualified web api that can create a meeting.  And we have swagger to test functions.

That’s good for a start…