💻 Take your coding skills to the next level with "500+ Ultimate ChatGPT Prompts For Developers" – the game-changer every developer needs, click here to order now.

Cursor-based iteration with Mongoose

Published November 17, 2021・Last updated May 28, 2023・1 min read

Using cursor-based iteration can be useful when there is a need to iterate (in memory) over all of the documents from a collection and every document is a big object. Every document can be projected to return only specific fields.

const cursor = Model.find().select('/* several fields */').cursor();
for (let document = await cursor.next(); document != null; document = await cursor.next()) {
  // ...
}

🔍

Async API documentation 101

May 21, 2023

Async API documentation is used for documenting events in event-driven systems, like Kafka events. All of the event DTOs are stored in one place. It supports YAML and JSON formats.

It contains information about channels and components. Channels and components are defined with their messages and DTO schemas, respectively.

{
  "asyncapi": "2.6.0",
  "info": {
    "title": "Events docs",
    "version": "1.0.0"
  },
  "channels": {
    "topic_name": {
      "publish": {
        "message": {
          "schemaFormat": "application/vnd.oai.openapi;version=3.0.0",
          "payload": {
            "type": "object",
            "properties": {
              "counter": {
                "type": "number"
              }
            },
            "required": [
              "counter"
            ]
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EventDto": {
        "type": "object",
        "properties": {
          "counter": {
            "type": "number"
          }
        },
        "required": [
          "counter"
        ]
      }
    }
  }
}

Autogeneration

Async API docs can be autogenerated by following multiple steps:

define DTOs and their required and optional fields with ApiProperty and ApiPropertyOptional decorators (from the @nestjs/swagger package), respectively
generate OpenAPI docs from the defined DTOs
parse and reuse component schemas from generated OpenAPI documentation to build channel messages and component schemas for Async API docs

Validation

Use AsyncAPI Studio to validate the written specification.

Preview

There are multiple options

AsyncAPI Studio
VSCode extension asyncapi-preview, open the command palette, and run the Preview AsyncAPI command.

UI generation

Install @asyncapi/cli and corresponding template package (e.g., @asyncapi/html-template, @asyncapi/markdown-template)
Update package.json with scripts

{
  "scripts": {
    // ...
    "generate-docs:html": "asyncapi generate fromTemplate ./asyncapi/asyncapi.json @asyncapi/html-template --output ./docs/html",
    "generate-docs:markdown": "asyncapi generate fromTemplate ./asyncapi/asyncapi.json @asyncapi/markdown-template --output ./docs/markdown"
  }
}

Health checks with Terminus

April 14, 2023

Monitoring tools use health checks to check if service and external dependencies (like a database) are up and running and take some action (like sending alerts) for the unhealthy state. Terminus provides a set of health indicators.

Liveness probe

An HTTP endpoint checks if the service is up and running.

// health.controller.ts
import { Controller, Get } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';
import {
  HealthCheck,
  HealthCheckResult,
  HealthCheckService,
  HealthIndicatorResult,
  TypeOrmHealthIndicator
} from '@nestjs/terminus';
import { CustomConfigService } from 'common/config/custom-config.service';
@ApiTags('health')
@Controller('health')
export class HealthController {
  constructor(
    private readonly healthCheckService: HealthCheckService,
    private readonly configService: CustomConfigService,
    private readonly database: TypeOrmHealthIndicator
  ) {}
  @Get('liveness')
  @HealthCheck()
  async check(): Promise<HealthCheckResult> {
    return this.healthCheckService.check([
      async (): Promise<HealthIndicatorResult> => ({
        [this.configService.SERVICE_NAME]: { status: 'up' }
      })
    ]);
  }
  // ...
}

A successful response is like the one below.

{
  "status": "ok",
  "info": {
    "nestjs-starter": {
      "status": "up"
    }
  },
  "error": {},
  "details": {
    "nestjs-starter": {
      "status": "up"
    }
  }
}

Readiness probe

An HTTP endpoint checks if the service is ready to receive the traffic and if all external dependencies are running.

// health.controller.ts
import { Controller, Get } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';
import {
  HealthCheck,
  HealthCheckResult,
  HealthCheckService,
  HealthIndicatorResult,
  TypeOrmHealthIndicator
} from '@nestjs/terminus';
import { CustomConfigService } from 'common/config/custom-config.service';
@ApiTags('health')
@Controller('health')
export class HealthController {
  constructor(
    private readonly healthCheckService: HealthCheckService,
    private readonly configService: CustomConfigService,
    private readonly database: TypeOrmHealthIndicator
  ) {}
  // ...
  @Get('readiness')
  @HealthCheck()
  async checkReadiness(): Promise<HealthCheckResult> {
    return this.healthCheckService.check([
      async (): Promise<HealthIndicatorResult> =>
        this.database.pingCheck('postgres')
    ]);
  }
}

Responses

Successful response

{
  "status": "ok",
  "info": {
    "postgres": {
      "status": "up"
    }
  },
  "error": {},
  "details": {
    "postgres": {
      "status": "up"
    }
  }
}

Unhealthy state will throw an exception

Linting with Eslint

April 5, 2023

Linting represents static code analysis based on specified rules. Please include it in the CI pipeline.

Setup

Run the following commands to generate the linter configuration using the eslint package.

npm init -y
npm init @eslint/config

Below is an example of the configuration. Some rules can be ignored or suppressed as warnings.

// .eslintrc.js
module.exports = {
  env: {
    commonjs: true,
    es2021: true,
    node: true,
    jest: true,
  },
  extends: 'airbnb-base',
  overrides: [
  ],
  parserOptions: {
    ecmaVersion: 'latest',
  },
  rules: {
    'import/no-extraneous-dependencies': 'warn',
    'import/prefer-default-export': 'off',
  },
};

Ignore the files with the .eslintignore file.

dist

Linting

Configure and run the script with the npm run lint command. Some errors can be fixed automatically with the --fix option.

// package.json
{
  "scripts": {
    // ...
    "lint": "eslint src",
    "lint:fix": "npm run lint -- --fix"
  }
}

Migrating Node.js app from Heroku to Fly.io

April 1, 2023

I recently migrated the Node.js app from Heroku to Fly.io, mainly due to reduced costs.

This blog post will cover the necessary steps in the migration process.

Prerequisites

Heroku app running
Use the exact versions for dependencies and dev dependencies in package.json so installation and build steps can pass successfully
Use the same Node.js version in Dockerfile, package.json, and GitHub Actions workflow
Use API gateway or custom domain for the service so web apps and mobile apps don't get affected by changing the URL of the service

Migration steps

Migrate environment variables and secrets
Migrate the Postgres database with the following commands (the ssl field in database configuration options is not needed)

fly secrets set HEROKU_DATABASE_URL=$(heroku config:get DATABASE_URL)
fly ssh console
apt update && apt install postgresql-client
pg_dump -Fc --no-acl --no-owner -d $HEROKU_DATABASE_URL | pg_restore --verbose --clean --no-acl --no-owner -d $DATABASE_URL
exit
fly secrets unset HEROKU_DATABASE_URL

Migrate the Redis database if it's used
Include the deployment step in the GitHub Actions workflow

References

Integration with ChatGPT API

March 19, 2023

ChatGPT is a large language model (LLM) that understands and processes human prompts to produce helpful responses. OpenAI provides an API to interact with the ChatGPT model (gpt-3.5-turbo).

Prerequisites

OpenAI account
Generated API key
Enabled billing

Integration

Below is an example of interacting with ChatGPT API based on a given prompt.

const handlePrompt = async (prompt) => {
  const response = await axios.post(
    'https://api.openai.com/v1/chat/completions',
    {
      model: 'gpt-3.5-turbo',
      messages: [
        {
          role: 'user',
          content: prompt,
        },
      ],
    },
    {
      headers: {
        Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
      },
    }
  );
  return response?.data?.choices?.[0]?.message?.content;
};

Documenting REST APIs with OpenAPI specs (NestJS/Swagger)

March 16, 2023

OpenAPI is a language-agnostic specification for declaring API documentation for REST APIs. It contains the following information:

API information like title, description, version
endpoints definitions with request and response parameters
DTOs and security schemas

openapi: 3.0.0
paths:
  /users:
    post:
      operationId: UsersController_createUser
      summary: Create user
      description: Create a new user
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserDto'
      responses:
        '201':
          description: 'User is created'
info:
  title: nestjs-starter
  description: Minimal NestJS boilerplate
  version: 0.1.0
  contact: {}
tags: []
servers: []
components:
  securitySchemes:
    token:
      type: apiKey
      scheme: api_key
      in: header
      name: auth-token
  schemas:
    CreateUserDto:
      type: object
      properties:
        firstName:
          type: string
          example: tester
          description: first name of the user
      required:
        - firstName

NestJS provides a Swagger plugin for generating the API docs.

Setup

Configure API documentation with the specified endpoint, like /api-docs, which shows the generated docs.

const SWAGGER_API_ENDPOINT = '/api-docs';
// ...
export const setupApiDocs = (app: INestApplication): void => {
  const options = new DocumentBuilder()
    .setTitle(SWAGGER_API_TITLE)
    .setDescription(SWAGGER_API_DESCRIPTION)
    .setVersion(SWAGGER_API_VERSION)
    .addSecurity('token', {
      type: 'apiKey',
      scheme: 'api_key',
      in: 'header',
      name: 'auth-token',
    })
    .addBearerAuth()
    .build();
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup(SWAGGER_API_ENDPOINT, app, document);
};

Configure the plugin in the NestJS config file.

{
  "compilerOptions": {
    "plugins": ["@nestjs/swagger"]
  }
}

JSON and YAML formats are generated at /api-docs-json and /api-docs-yaml endpoints, respectively.

Decorators

ApiTags groups endpoints

@ApiTags('users')
@Controller('users')
export class UsersController {
// ...
}

ApiOperation provides more details like a summary and description of the endpoint

@ApiOperation({
  summary: 'Get user',
  description: 'Get user by id',
})
@Get(':id')
async getById(
  @Param('id', new ParseUUIDPipe()) id: string,
): Promise<UserDto> {
// ...
}

@ApiProperty and @ApiPropertyOptional should be used for request and response DTOs fields. Example and description values will be shown in the generated documentation.

export class CreateUserDto {
  @ApiProperty({ example: 'John', description: 'first name of the user' })
  // ...
  public firstName: string;
  @ApiPropertyOptional({ example: 'Doe', description: 'last name of the user' })
  // ...
  public lastName?: string;
}

ApiHeader documents endpoint headers

@ApiHeader({
  name: 'correlation-id',
  required: false,
  description: 'unique id for correlated logs',
  example: '7ea2c7f7-8b46-475d-86f8-7aaaa9e4a35b',
})
@Get()
getHello(): string {
// ...
}

ApiResponse specifies which responses are expected, like error responses. NestJS' Swagger package provides decorators for specific status codes like ApiBadRequestResponse.

// ...
@ApiResponse({ type: NotFoundException, status: HttpStatus.NOT_FOUND })
@ApiBadRequestResponse({ type: BadRequestException })
@Get(':id')
async getById(
  @Param('id', new ParseUUIDPipe()) id: string,
): Promise<UserDto> {
  return this.userService.findById(id);
}
// ...

ApiSecurity('token') uses a custom-defined security strategy, token in this case. Other options are to use already defined strategies like ApiBearerAuth.

@ApiSecurity('token')
@Controller()
export class AppController {
// ...
}
// ...
@ApiBearerAuth()
@Controller()
export class AppController {
// ...
}

ApiExcludeEndpoint and ApiExcludeController exclude one endpoint and the whole controller, respectively.

export class AppController {
  @ApiExcludeEndpoint()
  @Get()
  getHello(): string {
    // ...
  }
}
// ...
@ApiExcludeController()
@Controller()
export class AppController {
  // ...
}

Importing API to Postman

Import JSON version of API docs as Postman API with Import → Link option (e.g., URL http://localhost:8081/api-docs-json). Imported API collection will be available in the APIs tab.

Deploying Next.js apps to Netlify

March 7, 2023

This post covers the main notes for deploying to Netlify and domain setup. Prerequisites Next.js app bootstrapped Deployment Add a new site…

Node.js built-in module functions as Promises

February 28, 2023

Node.js provides asynchronous methods for fs, dns, stream, and timers modules that return Promises.

const {
  createWriteStream,
  promises: { readFile }
} = require('fs');
const dns = require('dns/promises');
const stream = require('stream/promises');
const timers = require('timers/promises');
const sleep = timers.setTimeout;
const SLEEP_TIMEOUT_MS = 2000;
(async () => {
  const fileName = 'test-file';
  const writeStream = createWriteStream(fileName, {
    autoClose: true,
    flags: 'w'
  });
  await stream.pipeline('some text', writeStream);
  await sleep(SLEEP_TIMEOUT_MS);
  const readFileResult = await readFile(fileName);
  console.log(readFileResult.toString());
  const lookupResult = await dns.lookup('google.com');
  console.log(lookupResult);
})();

Use the promisify function to convert other callback-based functions to Promise-based.

const crypto = require('crypto');
const { promisify } = require('util');
const randomBytes = promisify(crypto.randomBytes);
const RANDOM_BYTES_LENGTH = 20;
(async () => {
  const randomBytesResult = await randomBytes(RANDOM_BYTES_LENGTH);
  console.log(randomBytesResult);
})();

Postgres and Redis containers with Docker Compose

February 26, 2023

Docker Compose allows spinning up containers for databases without installing the databases locally. This post covers the setup for Postgres and Redis images.

Prerequisites

Docker Compose installed

Configuration

The following configuration spins up Postgres and Redis containers with UI tools (Pgweb and Redis Commander).

Connection strings for Postgres and Redis are redis://localhost:6379 and postgres://username:password@localhost:5435/database-name.

Pgweb and Redis Commander are available at http://localhost:8085 and http://localhost:8081 links.

# docker-compose.yml
version: '3.8'
services:
  postgres:
    image: postgres:alpine
    environment:
      POSTGRES_DB: database-name
      POSTGRES_PASSWORD: password
      POSTGRES_USER: username
    ports:
      - 5435:5432
    restart: on-failure:3
  pgweb:
    image: sosedoff/pgweb
    depends_on:
      - postgres
    environment:
      DATABASE_URL: postgres://username:password@postgres:5432/database-name?sslmode=disable
    ports:
      - 8085:8081
    restart: on-failure:3
  redis:
    image: redis:latest
    command: redis-server
    volumes:
      - redis:/var/lib/redis
      - redis-config:/usr/local/etc/redis/redis.conf
    ports:
      - 6379:6379
    networks:
      - redis-network
  redis-commander:
    image: rediscommander/redis-commander:latest
    environment:
      - REDIS_HOSTS=local:redis:6379
      - HTTP_USER=root
      - HTTP_PASSWORD=qwerty
    ports:
      - 8081:8081
    networks:
      - redis-network
    depends_on:
      - redis
volumes:
  redis:
  redis-config:
networks:
  redis-network:
    driver: bridge

Run the following command to spin up the containers.

docker-compose up

GitHub actions 101

February 19, 2023

GitHub action is a CI/CD tool integrated within GitHub repositories that can run different kinds of jobs (building, testing, deployment). Store workflow files in .github/workflows inside the repository, which will be triggered based on specified conditions.

This post covers GitHub actions basics, from specifying the workflow name to configuring different jobs.

Name

Specify the name of the workflow with the name field.

# .github/workflows/config.yml
name: CI/CD pipeline

Running

on field specifies when the workflow should be running.

Automatically

The following configuration runs on every push to a specific branch.

# .github/workflows/config.yml
on:
  push:
    branches:
      - main

The following configuration runs on every push to every branch.

# .github/workflows/config.yml
on:
  push:
    branches:
      - "*"

Cron jobs

The following configuration runs at a specified interval (e.g., every hour).

# .github/workflows/config.yml
on:
  schedule:
    - cron: '0 * * * *'

Manual triggers

The following configuration enables manual triggering. Trigger it on the Actions tab by selecting the workflow and clicking the Run workflow button.

Use a manual trigger to upload apps to the Google Play console or update the GitHub profile Readme.

# .github/workflows/config.yml
on:
  workflow_dispatch:

Environment variables

Specify with the env field. Set repository secrets in Settings → Secrets and variables → Actions page.

# .github/workflows/config.yml
env:
  API_KEY: ${{ secrets.API_KEY }}

Jobs

Specify the job name with the name field. Otherwise, the workflow will use the jobs item as the job name.

Every job should have a runs-on field specified for the machine, which will be running on (e.g., ubuntu-latest) or container field with set Docker image (e.g., node:18.14-alpine3.16)

You can specify multiple tasks inside one job. Every task can have the following fields

name - task name
uses - GitHub action path from GitHub Marketplace
with - parameters for the specified GitHub action
run - bash commands
env - environment variables

# .github/workflows/config.yml
jobs:
  build:
    name: Custom build job
    runs-on: ubuntu-latest
    # container: node:18.14-alpine3.16
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Configure Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
      - name: Install and build
        run: |
          npm ci
          npm run build

Use the needs field for running jobs sequentially. It specifies a job that has to be finished before starting the next one. Otherwise, jobs will run in parallel.

# .github/workflows/config.yml
jobs:
  build:
    # ...
  deploy:
    name: Custom deploy job
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy
        run: |
          npm run deploy

Every job can run multiple times with different versions using a matrix strategy (e.g., Node versions 16 and 18 or multiple OS versions).

# .github/workflows/config.yml
jobs:
  build:
    name: Custom build job
    strategy:
      matrix:
        node-version: [16, 18]
        os: [ubuntu-22.04, ubuntu-20.04]
    runs-on: ${{ matrix.os }}
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Configure Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
      - name: Install and build
        run: |
          npm ci
          npm run build

Every job can provision databases for e2e tests with a services field like Postgres in the following example.

# .github/workflows/config.yml
jobs:
  build:
    name: Custom build job
    runs-on: ubuntu-latest
    strategy:
      matrix:
        database-name:
          - test-db
        database-user:
          - username
        database-password:
          - password
        database-host:
          - postgres
        database-port:
          - 5432
    services:
      postgres:
        image: postgres:latest
        env:
          POSTGRES_DB: ${{ matrix.database-name }}
          POSTGRES_USER: ${{ matrix.database-user }}
          POSTGRES_PASSWORD: ${{ matrix.database-password }}
        ports:
          - ${{ matrix.database-port }}:${{ matrix.database-port }}
        # Set health checks to wait until postgres has started
        options: --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      # ...
      - run: npm run test:e2e
        env:
          DATABASE_URL: postgres://${{ matrix.database-user }}:${{ matrix.database-password }}@${{ matrix.database-host }}:${{ matrix.database-port }}/${{ matrix.database-name }}

Passing artifacts between jobs can be done with uploading (actions/upload-artifact) and downloading (actions/download-artifact) actions.

# .github/workflows/config.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Configure Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
      - name: Install and build
        run: |
          npm ci
          npm run build
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: artifact
          path: public
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Download artifact
        uses: actions/download-artifact@v3
        with:
          name: artifact
      # ...

Running locally

You can use act to run GitHub actions locally.

Install it and run it with the following commands.

curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
cp ./bin/act /usr/local/bin/act
act

Error tracking with Sentry

February 14, 2023

Error tracking and alerting are crucial in the production environment, proactively fixing the errors leads to a better user experience. Sentry is one of the error tracking services, and it provides alerting for unhandled exceptions. You should receive an email when something wrong happens.

Sentry issues show the error stack trace, device, operating system, and browser information. The project dashboard shows an unhandled exception once it's thrown. This post covers the integration of several technologies with Sentry.

Node.js

Create a Node.js project on Sentry
Install the package

npm i @sentry/node

Run the following script

const Sentry = require('@sentry/node');
Sentry.init({
  dsn: SENTRY_DSN
});
test();

Next.js

Create a Next.js project on Sentry (version 13 is not yet supported)
Run the following commands for the setup

npm i @sentry/nextjs
npx @sentry/wizard -i nextjs

Gatsby

Create a Gatsby project on Sentry
Install the package

npm i @sentry/gatsby

Add plugin in Gatsby config

module.exports = {
  plugins: [
    // ...
    {
      resolve: '@sentry/gatsby',
      options: {
        dsn: SENTRY_DSN
      }
    }
  ]
};

React Native

Create a React Native project on Sentry
Run the following commands for the setup

npm i @sentry/react-native
npx @sentry/wizard -i reactNative -p android

Logging practices

February 7, 2023

This post covers some logging practices for the back-end (Node.js) apps.

Avoid putting unique identifiers (e.g., user id) within the message. A unique id will produce a lot of different messages with the same context. Use it as a message parameter.
Use the appropriate log level for the message. There are multiple log levels
- info - app behavior, don't log every single step
- error - app processing failure, something that needs to be fixed
- debug - additional logs needed for troubleshooting
- warning - something unexpected happened (e.g., third-party API fails)
- fatal - app crash, needs to be fixed as soon as possible

Don't use the debug logs on production. Put log level as an environment variable.

Stream logs to the standard output in JSON format so logging aggregators (Graylog, e.g.) can collect and adequately parse them
Avoid logging any credentials, like passwords, auth tokens, etc.
Put correlation ID as a message parameter for tracing related logs.
Use a configurable logger like pino

const pino = require('pino');
const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  redact: {
    paths: ['token'],
    remove: true,
  },
});
logger.info({ someId: 'id' }, 'Started the app...');
const correlationId = request.headers['correlation-id'] || uuid.v4();
logger.debug({ data: 'some data useful for debugging', correlationId }, 'Sending the request...');

Vim overview

February 5, 2023

Vim is a text editor known for editing files without using a mouse. It's also useful when you SSH into a remote server, and you have to edit some files there. This post covers the main notes from installation to its usage (shortcuts, commands, configuration).

Installation

Vim is usually already installed on mostly *nix operating systems. You can install it via the package manager and open it with the following commands.

sudo apt-get update
sudo apt-get install -y vim
vim

Modes

Vim has four modes

Normal - this is the default mode. It enables scrolling through the file content
Visual - type v, and you can select text content for deleting and copying with scrolling shortcuts
Insert - type i, and you can start editing the file content
Command-line - type : and some command plus Enter to run the command

Usage

Shortcuts

Esc - go back to Normal mode
h to scroll left
j to scroll down
k to scroll up
l to scroll right
Shift + g - scroll to the end of the file
g + g - scroll to the beginning of the file
line number + Shift + g, (e.g., 5 + Shift + g) - jump to the specific line number, 5th in this case
^ - jump to the start of the current line
$ - jump to the end of the current line
w - move to the next word
b - move back to the previous word

Commands

:edit script.js - create a new file or open the existing one
:w - save the changes
:q - exit the file
:wq - save the changes and exit the file
:q! - exit without the changes
:%s/<text>/<new text>/g - find and replace the occurrences within the whole file (e.g., :%s/Vim/Emacs/g)
: + ↑ - to find the previous command

Miscellaneous

Copy pasting
- enter the visual mode, scroll through the text you want to copy, type y, then scroll to the place you want to paste it and type p
- type y + number of lines + y to copy specified lines and paste it with p
Deleting
- enter the visual mode, scroll through the text you want to delete, and type d
- type d + number of lines + d to delete specified lines
- type x to remove the letter
- type dw to remove the word (and the space after it)
Type u to undo the previous change
Type CTRL + r to redo the previous undo
Find specific text with /<text> like /vim and press Enter. Type n to go to the next occurrence and N to the previous one

Configuration

Vim configuration is stored in ~/.vimrc file. You can specify plugins and other configurations, like theme, tabs spaces, etc.

To use plugins, install the vim-plug plugin manager with the following command

curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
  https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

and run the :PlugInstall command.

Check the status of the plugins with the :PlugStatus command.

Below is the configuration I use.

"------PLUGINS SETTINGS---------
set nocompatible              " be iMproved, required
filetype off                  " required
call plug#begin('~/.vim/plugged')
Plug 'vim-airline/vim-airline'
Plug 'vim-airline/vim-airline-themes'
Plug 'Raimondi/delimitMate'
Plug 'flazz/vim-colorschemes'
Plug 'prettier/vim-prettier', { 'do': 'npm install' }
Plug 'tpope/vim-commentary'
" All of your Plugins must be added before the following line
call plug#end()              " required
filetype plugin indent on    " required
"---------AIRLINE SETTINGS------
let g:airline_powerline_fonts = 1
let g:airline_theme='solarized'
"-----COMMENTARY SETTINGS-------
noremap <leader>/ :Commentary<cr>
"-----PRETTIER SETTINGS---------
let g:prettier#autoformat = 1
let g:prettier#autoformat_require_pragma = 0
"------------TABS---------------
set expandtab
set tabstop=2
set shiftwidth=2
set softtabstop=2
" makefile tabs
autocmd FileType make setlocal noexpandtab
" tab completion
set wildmenu
" line numbers
set number
set relativenumber
syntax on
" theme
colorscheme molokai
let g:solarized_termcolors=256
set background=dark
" indention
set autoindent
" highlight found words
set hlsearch
" press left/right and move to the previous/next line after reaching the first/last character in the line
set whichwrap+=<,>,h,l,[,]
" long lines
nnoremap k gk
nnoremap j gj
" disable arrow keys in normal mode
map <Left> <Nop>
map <Right> <Nop>
map <Up> <Nop>
map <Down> <Nop>
" toggling paste mode
set pastetoggle=<F2>
" last command
set showcmd
" disable swap files and backups
set noswapfile
set nobackup
set nowritebackup
" mouse click navigation
set mouse=a

Further learning

Try vimtutor with the following command to dive deep into Vim features.

vimtutor

Deploying Next.js apps to Vercel

February 3, 2023

This post covers the main notes for deploying to Vercel and domain setup. Prerequisites Next.js app bootstrapped Deployment Add a new…

Hosting static websites on GitHub pages

February 2, 2023

This post covers instructions for deploying to GitHub pages and domain setup. GitHub Pages GitHub provides a way to host a static website (e…

Integration testing Node.js apps

January 25, 2023

Integration testing means testing a component with multiple sub-components and how they interact. Some sub-components can be external services, databases, and message queues.

External services are running, but their business logic is mocked based on received parameters (request headers, query parameters, etc.). Databases and message queues are spun up using test containers.

This post covers testing service as a component and its API endpoints. This approach can be used with any framework and language. NestJS and Express are used in the examples below.

API endpoints

Below is the controller for two endpoints. First communicates with an external service and retrieves some data based on the sent parameter. The second one retrieves the data from the database.

// users.controller.ts
@Controller('users')
export class UsersController {
  constructor(private userService: UsersService) {}
  @Get()
  async getAll(@Query('type') type: string) {
    return this.userService.findAll(type);
  }
  @Get(':id')
  async getById(@Param('id', new ParseUUIDPipe()) id: string) {
    return this.userService.findById(id);
  }
}

External dependencies

External service is mocked to send data based on the received parameter.

export const createDummyUserServiceServer = async (): Promise<DummyServer> => {
  return createDummyServer((app) => {
    app.get('/users', (req, res) => {
      if (req.query.type !== 'user') {
        return res.status(403).send('User type is not valid');
      }
      res.json(usersResponse);
    });
  });
};

Tests setup

Tests for endpoints can be split into two parts. The first is related to the external dependencies setup.

The example below creates a mocked service and spins up the database using test containers. The environment variables are set for before mentioned dependencies, and the leading service starts running.

The database is cleaned before every test run. External dependencies (mocked service and database) are closed after tests finish.

// test/users.spec.ts
describe('UsersController (integration)', () => {
  let app: INestApplication;
  let dummyUserServiceServerClose: () => void;
  let postgresContainer: StartedTestContainer;
  let usersRepository: Repository<UsersEntity>;
  const databaseConfig = {
    databaseName: 'nestjs-starter-db',
    databaseUsername: 'user',
    databasePassword: 'some-r4ndom-pasS',
    databasePort: 5432,
  }
  beforeAll(async () => {
    const dummyUserServiceServer = await createDummyUserServiceServer();
    dummyUserServiceServerClose = dummyUserServiceServer.close;
    postgresContainer = await new GenericContainer('postgres:15-alpine')
      .withEnvironment({
        POSTGRES_USER: databaseConfig.databaseUsername,
        POSTGRES_PASSWORD: databaseConfig.databasePassword,
        POSTGRES_DB: databaseConfig.databaseName,
      })
      .withExposedPorts(databaseConfig.databasePort)
      .start();
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [AppModule],
    })
      .overrideProvider(ConfigService)
      .useValue({
        get: (key: string): string => {
          const map: Record<string, string | undefined> = process.env;
          map.USER_SERVICE_URL = dummyUserServiceServer.url;
          map.DATABASE_HOSTNAME = postgresContainer.getHost();
          map.DATABASE_PORT = `${postgresContainer.getMappedPort(databaseConfig.databasePort)}`;
          map.DATABASE_NAME = databaseConfig.databaseName;
          map.DATABASE_USERNAME = databaseConfig.databaseUsername;
          map.DATABASE_PASSWORD = databaseConfig.databasePassword;
          return map[key] || '';
        },
      })
      .compile();
    app = moduleFixture.createNestApplication();
    usersRepository = app.get(getRepositoryToken(UsersEntity));
    await app.init();
  });
  beforeEach(async () => {
    await usersRepository.delete({});
  });
  afterAll(async () => {
    await app.close();
    dummyUserServiceServerClose();
    await postgresContainer.stop();
  });
  // ...
});

Tests

The second part covers tests for the implemented endpoints. The first test suite asserts retrieving data from the external service based on the sent type as a query parameter.

// test/users.spec.ts
describe('/users (GET)', () => {
  it('should return list of users', async () => {
    return request(app.getHttpServer())
      .get('/users?type=user')
      .expect(HttpStatus.OK)
      .then((response) => {
        expect(response.body).toEqual(usersResponse);
      });
  });
  it('should throw an error when type is forbidden', async () => {
    return request(app.getHttpServer())
      .get('/users?type=admin')
      .expect(HttpStatus.FORBIDDEN);
  });
});

The second test suite asserts retrieving the data from the database.

// test/users.spec.ts
describe('/users/:id (GET)', () => {
  it('should return found user', async () => {
    const userId = 'b618445a-0089-43d5-b9ca-e6f2fc29a11d';
    const userDetails = {
      id: userId,
      firstName: 'tester',
    };
    const newUser = await usersRepository.create(userDetails);
    await usersRepository.save(newUser);
    return request(app.getHttpServer())
      .get(`/users/${userId}`)
      .expect(HttpStatus.OK)
      .then((response) => {
        expect(response.body).toEqual(userDetails);
      });
  });
  it('should return 404 error when user is not found', async () => {
    const userId = 'b618445a-0089-43d5-b9ca-e6f2fc29a11d';
    return request(app.getHttpServer())
      .get(`/users/${userId}`)
      .expect(HttpStatus.NOT_FOUND);
  });
});

Boilerplate

Here is the link to the boilerplate I use for the development. It contains the examples mentioned above with more details.

Automated captcha solver

January 22, 2023

Many websites use CAPTCHAs to prevent bots from submitting forms and accessing their services. CAPTCHA is designed to separate humans from…

Internal testing React Native Android apps

January 21, 2023

Internal testing on Google Play Console is used for testing new app versions before releasing them to the end users. This post covers the main notes from setting up the app (on the Google Play Console) to automatic uploads.

Prerequisites

bootstrapped app
installed Android studio
verified developer account on Google Play Console
paid one-time fee (25$)

Google Play Console setup

Create an app with the essential details, such as app name, default language, and app type, and choose if it is paid or free.

Testers

Add email addresses to the email list.

Release

Signing config

Generate a private signing key with a password using keytool

sudo keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Move the generated file to android/app directory.

Edit ~/.gradle/gradle.properties to add the following keys and replace the alias and password with the correct values.

MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias
MYAPP_UPLOAD_STORE_PASSWORD=*****
MYAPP_UPLOAD_KEY_PASSWORD=*****

Edit android/app/build.gradle to add the release signing config, which uses the generated key.

android {
  ...
  defaultConfig { ... }
  signingConfigs {
    ...
    release {
      if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
          storeFile file(MYAPP_UPLOAD_STORE_FILE)
          storePassword MYAPP_UPLOAD_STORE_PASSWORD
          keyAlias MYAPP_UPLOAD_KEY_ALIAS
          keyPassword MYAPP_UPLOAD_KEY_PASSWORD
      }
    }
  }
  buildTypes {
    ...
    release {
      ...
      signingConfig signingConfigs.release
    }
  }
}

Versioning

Update versionCode and versionName fields in android/app/build.gradle file before generating the bundle. The version code should be incremented by 1.

android {
  ...
  defaultConfig {
    ...
    versionCode 2
    versionName "1.1.0"
    ...
  }
...

Android App Bundle (aab file)

Generate the Android app bundle with the following command.

cd android
./gradlew bundleRelease

android/app/build/outputs/bundle/release/app-release.aab is the path for the generated file.

Manual uploads

Upload the aab file and write the release name and notes. The link for downloading the app should be available on the Testers tab.

Automatic uploads

This section configures the necessary steps for the pipeline with Github actions.

Versioning

Version apps with np and react-native-version packages running np script.

// package.json
{
  "scripts": {
    "np": "np --no-publish",
    "postversion": "react-native-version -t android"
  },
  "repository": {
    "type": "git",
    "url": "<REPOSITORY_URL>"
  }
}

Signing config

Remove the release signing config from android/app/build.gradle file. An app will be bundled first and signed after that.

Credentials

Get the signing key with the following command and set it as ANDROID_SIGNING_KEY Github action secret in the Settings → Secrets → Actions page.

cd android/app
openssl base64 < my-upload-key.keystore  | tr -d '\n' | tee my-upload-key.keystore.base64.txt

Reuse credentials from ~/.gradle/gradle.properties file and set them as Github secrets.

MYAPP_UPLOAD_STORE_PASSWORD → ANDROID_KEY_STORE_PASSWORD
MYAPP_UPLOAD_KEY_ALIAS → ANDROID_ALIAS
MYAPP_UPLOAD_KEY_PASSWORD → ANDROID_KEY_PASSWORD

For automatic uploads, create a service account by following the next steps.

go to Google Play console → Setup → API Access → Google Cloud project, create a Google Cloud project, and link it
on the same page, go to Credentials → Service accounts heading and click on Learn how to create service accounts, follow the mentioned steps
- create a service account with a service account user role
- click on Actions → Manage keys button and create JSON key, which will be downloaded
set downloaded JSON file as ANDROID_SERVICE_ACCOUNT_JSON_TEXT Github secret

Pipeline

The following pipeline sets up the necessary tools, does CI checks (linting, testing, audit), generates the app bundle, signs it, and uploads it to the Google Play console.

name: Android Build
on:
  push:
    branches:
      - release
jobs:
  android-build:
    name: Android Build
    runs-on: ubuntu-latest
    steps:
      - name: Check out Git repository
        uses: actions/checkout@v3
      - name: Set up JDK
        uses: actions/setup-java@v3
        with:
          java-version: 18
          distribution: temurin
      - name: Set up Android SDK
        uses: android-actions/setup-android@v2
      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm audit
      - name: Make Gradlew Executable
        run: cd android && chmod +x ./gradlew
      - name: Generate App Bundle
        run: |
          cd android && ./gradlew clean && \
          ./gradlew bundleRelease --no-daemon
      - name: Sign App Bundle
        id: sign_aab
        uses: r0adkll/sign-android-release@v1
        with:
          releaseDirectory: android/app/build/outputs/bundle/release
          signingKeyBase64: ${{ secrets.ANDROID_SIGNING_KEY }}
          alias: ${{ secrets.ANDROID_ALIAS }}
          keyStorePassword: ${{ secrets.ANDROID_KEY_STORE_PASSWORD }}
          keyPassword: ${{ secrets.ANDROID_KEY_PASSWORD }}
      - name: Upload App Bundle to Google Play
        uses: r0adkll/upload-google-play@v1
        with:
          serviceAccountJsonPlainText: ${{ secrets.ANDROID_SERVICE_ACCOUNT_JSON_TEXT }}
          packageName: com.flatmeapp
          releaseFiles: android/app/build/outputs/bundle/release/*.aab
          track: internal
          status: draft
          inAppUpdatePriority: 2

Edit the draft release and roll it out.

Troubleshooting

In case of a problem with signatures not matching the previously installed version, uninstall the app with the following commands.
```
adb devices
# adb -s <DEVICE_KEY> uninstall <PACKAGE_NAME>
adb -s emulator-5554 uninstall "com.yourapp"
```
If the link for downloading the app installs some old version, clear the cache and data of the Google Play Store app on your device

Deploying Node.js apps to Heroku

January 18, 2023

This post covers the main notes from setting up the Heroku CLI tool to CI/CD pipeline with Github actions . Prerequisites Run the following…

Markdown overview

January 15, 2023

Markdown is a markup language mainly used for writing documentation. Its extension is .md, and most of the IDEs provide a previewer of the written documents. This post will cover basic syntax, some use cases with examples, and different flavors.

Basics

Headers
- # some text for h1 header
- ## some text for h2 header
- ### some text for h3 header
- #### some text for h4 header
- ##### some text for h5 header
- ###### some text for h6 header
Blockquotes
- > some text
Links
- External links
  - [link text](link URL)
- Internal links (e.g., the link to Gitlab flavored header)
  - ```
  [Gitlab flavored](#gitlab-flavored)
```
Images
- ![image description](image URL)
Space between paragraphs
- blank line

Lists

unordered

- list item
  - sublist item
- list item
  - subitem item

ordered
```
1. post
1. post
1. post
```

Text modifications
- Highlighted
  - ```
  `text`
```
- Bold
  - ```
  **text**
```
- Italic
  - ```
  *text*
```
- Underlined
  - ```
  <u>underlined</u>
```
- Strike-through
  - ```
  ~~some text~~
```

Tables

| Hackathon | Location | Date |
| --------- | -------- | ---- |
| [hackathon](URL) | place | 1-2 June 2023 |

Code snippets with syntax highlighting
- ```
```js
  console.log('Hello world');
```
```
HTML tags and entities
- ```
<p>paragraph with some text &lt;3</p>
```
Comments
- ```

```
Escape characters
- ```
\> not a blockquote text
```
Show markdown content without rendering

````markdown
```js
console.log('Hello world');
```
````

~~~
```js
console.log('Hello world');
```
~~~

Usage

Documentation

Every repository should contain a Readme file with (at least) a project description and instructions on how to set up the project, run it, run the tests, and which technologies are used. Here is the link to the template example.

Blog posts

This post is written in Markdown and converted to HTML.

Diagrams

Different diagrams can be written in PlantUML. Check the rendered output in PlantUML editor.

Sequence diagrams

@startuml
User -> PaymentService: POST /payments
PaymentService -> PaymentService: handlePayment()
PaymentService -> User: response
@enduml

Architecture diagrams

@startuml
title Calculation
package calculationService {
  database postgres {
    collections scores
    collections users
  }
  interface POST_calculations
  interface GET_calculated_scores
  component calculator
  component scoreService
  interface userEventConsumer
}
package worker {
  component scheduler
  interface userEventProducer
}
package gateway {
  interface GET_scores
}
file USER_EVENT
actor User
userEventProducer --> USER_EVENT: Message event flow
USER_EVENT --> userEventConsumer: Message event flow
userEventConsumer --> users: keep users updated
scheduler --> POST_calculations: trigger calculation
POST_calculations --> calculator: calculate scores
calculator --> scores: store scores
User -> GET_scores: get scores
GET_scores --> GET_calculated_scores: get scores
GET_calculated_scores --> scoreService: get scores
scoreService --> scores: get scores
@enduml

Flavors

GitHub flavored
- Task lists
  - ```
  - [x] completed
  - [ ] in progress
```
- Emojis
  - ```
  :tada:
```

Gitlab flavored

Task lists

- [x] completed
- [~] inapplicable
- [ ] in progress

Emojis
- ```
:tada:
```
Table of content
- ```
[[_TOC_]]
```

Miscellaneous

Front matter

It is metadata placed at the beginning of the file before the content. This data can be used by static site generators like Gatsby or blogging platforms like dev.to.

---
title: Markdown overview
published: true
tags: ['markdown']
cover_image: https://picsum.photos/200/300
canonical_url: https://sevic.dev/notes/markdown-overview/
---

Mdx

Allows using JSX in Markdown documents.

import { Dashboard } from './dashboard.js'
<Dashboard year={2023} />

Git cheatsheet

January 6, 2023

Git is one of the version control systems, and it's a prerequisite for development jobs. This post covers most of the git commands I use.

Configuration

Set user configuration for every project if you use multiple accounts

git config user.name "<USERNAME>"
git config user.email "<EMAIL_ADDRESS>"

Use the current branch for push commands

git config --global push.default current

SSH keys setup

Generate separate SSH keys for Github and Bitbucket with the following command, type the filename path and passphrase.
```
ssh-keygen
```
Add generated public keys to Github and Bitbucket

Run the following commands to activate SSH keys

eval `ssh-agent -s`
ssh-add ~/.ssh/id_rsa_github
ssh-add ~/.ssh/id_rsa_bitbucket

Basic commands

The repository setup

Initialize a git repository
```
git init
```

Clone an existing repository

# git clone <REPOSITORY_URL>
git clone git@github.com:zsevic/pwa-starter.git

Add the remote repository

# git remote add <REMOTE_NAME> <REPOSITORY_URL>
git remote add origin git@github.com:zsevic/pwa-starter.git
git remote add upstream git@github.com:zsevic/pwa-starter.git

Update the URL for the remote repository

# git remote set-url <REMOTE_NAME> <REPOSITORY_URL>
git remote set-url origin git@github.com:zsevic/pwa-starter.git

Get a list of configured remote connections
```
git remote -v
```

Branches

Get a list of the branches
```
git branch
```
Create and switch to the new branch
```
git checkout -b new-branch
```

Checkout to a specific commit and create a new branch out of it

git log # find a hash from a specific commit
git checkout <COMMIT_HASH>
git switch -c <NEW_BRANCH_NAME>

Switch to another branch
```
git checkout existing-branch
```
Rename the current branch
```
git branch -m <NEW_BRANCH_NAME>
```
Delete branch
```
git branch -D other-existing-branch
```
Fetch all the remote branches
```
git fetch --all
```

Get the status of the local changes
```
git status
```
Add new changes
```
git add some-file.js
git add .
```
Commits
- Commit the changes
```
git commit -m "Commit message"
```
- Empty commit without any files
```
git commit --allow-empty -m "Trigger CI pipeline"
```
- Commit the changes and skip running git hooks
```
git commit -m "Commit message" --no-verify
```
- Update the latest commit message and add new changes to the latest commit
```
git commit -m "Commit message" --amend
```
Push the changes to the remote repository
- Push the changes to the current branch when the current branch is configured as the default one
```
git push
```
- Push the changes to the remote branch
```
# git push <REMOTE_NAME> <BRANCH_NAME>
git push origin master
```
- Force push the changes to the feature branch
```
# git push <REMOTE_NAME> <FEATURE_BRANCH_NAME>
git push origin feature-branch -f
```

Fetch and merge remote changes to the local branch

# git pull <REMOTE_NAME> <BRANCH_NAME>
git pull origin master

Remove (unstage) the changes from the local stage
```
git reset some-file.js
git reset
```
Differences between commits
- Get a difference compared to the latest commit
```
git diff some-file.js
git diff
```
- Get a difference between the last two commits
```
git diff HEAD^ HEAD
```
Revert the file changes
```
git checkout -- some-file.js
```
Merge the specified branch into the current one
```
git merge <BRANCH_NAME>
```
Revert specific commit. The following command creates a new commit
```
git revert <COMMIT_HASH>
```

Miscellaneous

Resets

Soft reset (commits are removed, but changes from the removed commits are staged)

# git reset --soft HEAD~{NUMBER_OF_COMMITS_TO_SOFT_REMOVE}
git reset --soft HEAD~2

Hard reset (both commits and changes are removed)

# git reset --hard HEAD~{NUMBER_OF_COMMITS_TO_HARD_REMOVE}
git reset --hard HEAD~1 # equal as git reset --hard HEAD^

Get the latest remote changes when pulling doesn't work
```
git reset --hard origin/<BRANCH_NAME>
```

Stashing

git add .
git stash save <STASH_NAME>
git stash list
git stash apply --index 0

Tags
- Remove the following tag locally
```
git tag -d v0.13.29
```
Find removed commits
```
git reflog
git checkout <COMMIT_HASH>
```
Remove the initial commit
```
git update-ref -d HEAD
```

Patching

Create a patch from the latest commits

# git format-patch -{NUMBER_OF_COMMITS}
git format-patch -1

Apply the patches
```
git apply 0001-latest-commit.patch
```

Git submodules

Add git submodule

# git submodule add -- <REPOSITORY_URL> <DIRECTORY_PATH>
git submodule add -- git@github.com:zsevic/pwa-starter.git template

Retrieve the latest changes for the git submodule

# git submodule update --remote <DIRECTORY_PATH>
git submodule update --remote template

2022

Debugging Node.js apps with Visual Studio Code debugger

December 28, 2022

Rather than doing it with console logs, debugging with a debugger and breakpoints is recommended. VSCode provides a built-in debugger for JavaScript-based apps. This post covers configuring and running a debugger for different kinds of Node.js apps in VSCode.

Configuration basics

VSCode configurations can use runtime executables like npm and ts-node. The beforementioned executables should be installed globally before running the configurations. A configuration can use the program field to point to the binary executable package inside node_modules directory to avoid installing packages globally. Runtime executables and programs can have arguments defined in runtimeArgs and args fields, respectively.

A configuration can have different requests: attach - the debugger is attached to the running process, and launch - the debugger launches a new process and wraps it. There are multiple configurations: node - runs the program from program field, and logs are shown in debug console, and node-terminal - runs the command from command field and shows the logs in the terminal.

The configuration file is .vscode/launch.json. The selected configuration on the Run and Debug tab is used as the default one.

Launch configs

Node

Below are examples of configurations for running Node processes with the debugger.

{
  "version": "0.2.0",
  "configurations": [
    // ...
    {
      "name": "Launch script in debug console",
      "program": "index.js", // update entry point
      "request": "launch",
      "type": "node",
      "skipFiles": [
        "<node_internals>/**"
      ]
    },
    {
      "name": "Launch script in the terminal",
      "command": "node index.js", // update entry point
      "request": "launch",
      "type": "node-terminal",
      "skipFiles": [
        "<node_internals>/**"
      ]
    }
  ]
}

Running npm scripts in debug mode

The debugger launches the following script in both configurations, dev in this case.

{
  "version": "0.2.0",
  "configurations": [
    // ...
    {
      "name": "Launch dev script in debug console",
      "runtimeExecutable": "npm",
      "runtimeArgs": [
        "run",
        "dev"
      ],
      "request": "launch",
      "type": "node",
      "skipFiles": [
        "<node_internals>/**"
      ]
    },
    {
      "name": "Launch dev script in the terminal",
      "command": "npm run dev",
      "request": "launch",
      "type": "node-terminal"
    }
  ]
}

ts-node

The following configurations will wrap the debugger around ts-node entry point.

{
  "version": "0.2.0",
  "configurations": [
    // ...
    {
      "name": "Launch ts-node script in debug console",
      "program": "node_modules/.bin/ts-node",
      "args": ["index.ts"], // update entry point
      "request": "launch",
      "type": "node",
      "skipFiles": [
        "<node_internals>/**"
      ]
    },
    {
      "name": "Launch ts-node script in the terminal",
      "command": "ts-node index.ts", // update entrypoint
      "request": "launch",
      "type": "node-terminal",
      "skipFiles": [
        "<node_internals>/**"
      ]
    }
  ]
}

@babel/node

The following configuration will wrap the debugger around babel-node entry point.

{
  "version": "0.2.0",
  "configurations": [
    // ...
    {
      "name": "Launch babel-node script in debug console",
      "program": "node_modules/.bin/babel-node",
      "args": ["src"], // update entry point
      "request": "launch",
      "type": "node",
      "skipFiles": [
        "<node_internals>/**"
      ]
    }
  ]
}

Nodemon

Add new configuration with Run → Add configuration option, select Node.js: Nodemon Setup, update program field to point to the nodemon executable package, also add arguments with args field to point to the entry point.

{
  "version": "0.2.0",
  "configurations": [
    // ...
    {
      "name": "Launch nodemon script in debug console",
      "program": "node_modules/.bin/nodemon",
      "args": ["-r", "dotenv/config", "--exec", "babel-node", "src/index.js"], // update entry point
      "request": "launch",
      "type": "node",
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen",
      "restart": true,
      "skipFiles": [
        "<node_internals>/**"
      ]
    }
  ]
}

Mocha

Add a new configuration, choose Node.js: Mocha Tests configuration, and replace tdd with bdd as u parameter and program field to point to the mocha executable package.

{
  "version": "0.2.0",
  "configurations": [
    // ...
    {
      "name": "Launch mocha tests",
      "program": "node_modules/.bin/mocha",
      "args": [
        "-u",
        "bdd",
        "--timeout",
        "999999",
        "--colors",
        "test"
      ],
      "request": "launch",
      "type": "node",
      "internalConsoleOptions": "openOnSessionStart",
      "skipFiles": [
        "<node_internals>/**"
      ]
    }
  ]
}

Attach configs

Auto Attach should be activated in settings with the With Flag value. In that case, auto-attaching is done when --inspect flag is given. The debugger should be attached when some of the following scripts are executed.

{
  // ...
  "scripts": {
    // ...
    "start:debug": "node --inspect index.js", // update entry point
  }
}

Jest

{
  // ...
  "scripts": {
    // ...
    "test:debug": "node --inspect -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
  }
}

NestJS

{
  // ...
  "scripts": {
    // ...
    "start:debug": "nest start --debug --watch"
  }
}

Debugging basics

During the debugging, the variables tab shows local variables. The step over option goes to the following statement in the codebase, while step into option goes deeper into the current statement. Log points can add logs in debug console when a certain part of the codebase is executed without pausing the process.

Preparation tips for live-coding interviews

December 19, 2022

Live coding is usually part of a technical interview where a candidate gets a task and demonstrates the coding solution in front of interviewers. As a candidate and interviewer, I have experience with both sides, so this post covers an opinionated list of tips.

Communication

Good written and verbal skills in the English language are essential so candidates can understand the task, explain the solution and ask understandable questions.

Technical preparation

Include pair programming sessions in your daily workflow so you feel comfortable when someone looks into your screen while you're coding. Include git in your daily workflow since some of the challenge requirements could be to clone a specific repository and start working on it instead of writing the solution from scratch.

Prepare yourself with data structures fundamentals knowing when you should use them, for example, why and when it's better to use a hash map instead of a two-dimensional array. Prepare yourself with the most used built-in methods for strings and arrays for the programming language you use during the interview.

If your current job role consists of more management duties, take some time to practice the syntax of the chosen programming language. Read the Clean Code book to dive deeper into writing clean code.

During the interview

Use the programming language you're most comfortable with if requirements are not strictly coupled to one programming language. Share your thoughts while you're coding so the interviewers can feel your way of thinking and problem-solving. Also, ask questions when something needs to be clarified for you.

Try not to write pieces of code you don't fully understand, for example, using IIFE and not knowing how to pass an argument into it, using ; in front of it, and not knowing why it's used. Try to write readable code with understandable variable and function names.

Avoid writing too nested statements, so it's not easy to understand the code's flow. Try to write code that is easy to cover with the tests.

TypeORM with NestJS

December 1, 2022

This post covers TypeORM examples with the NestJS framework, from setting up the connection with the Postgres database to working with transactions. The following snippets can be adjusted and reused with other frameworks like Express. The same applies to SQL databases.

Prerequisites

NestJS app bootstrapped
Postgres database running
@nestjs/typeorm, typeorm and pg packages installed

Database connection

It requires the initialization of the DataSource configuration.

// app.module.ts
const typeOrmConfig = {
  imports: [
    ConfigModule.forRoot({
      load: [databaseConfig]
    })
  ],
  inject: [ConfigService],
  useFactory: async (configService: ConfigService) =>
    configService.get('database'),
  dataSourceFactory: async (options) => new DataSource(options).initialize()
};
@Module({
  imports: [TypeOrmModule.forRootAsync(typeOrmConfig)]
})
export class AppModule {}

DataSource configuration contains elements for the connection string, migration details, etc.

// config/database.ts
import path from 'path';
import { registerAs } from '@nestjs/config';
import { PostgresConnectionOptions } from 'typeorm/driver/postgres/PostgresConnectionOptions';
export default registerAs(
  'database',
  (): PostgresConnectionOptions =>
    ({
      logging: false,
      entities: [path.resolve(`${__dirname}/../../**/**.entity{.ts,.js}`)],
      migrations: [
        path.resolve(`${__dirname}/../../../database/migrations/*{.ts,.js}`)
      ],
      migrationsRun: true,
      migrationsTableName: 'migrations',
      keepConnectionAlive: true,
      synchronize: false,
      type: 'postgres',
      host: process.env.DATABASE_HOSTNAME,
      port: Number(process.env.DATABASE_PORT),
      username: process.env.DATABASE_USERNAME,
      password: process.env.DATABASE_PASSWORD,
      database: process.env.DATABASE_NAME
    } as PostgresConnectionOptions)
);

Migrations and seeders

Migrations are handled with the following scripts for generation, running, and reverting.

// package.json
{
  "scripts": {
    "migration:generate": "npm run typeorm -- migration:create",
    "migrate": "npm run typeorm -- migration:run -d src/common/config/ormconfig-migration.ts",
    "migrate:down": "npm run typeorm -- migration:revert -d src/common/config/ormconfig-migration.ts",
    "typeorm": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js"
  }
}

A new migration is generated at the provided path with the following command. The filename of it is in the format <TIMESTAMP>-<MIGRATION_NAME>.ts.

npm run migration:generate database/migrations/<MIGRATION_NAME>

Here is the example for the migration which creates a new table. A table is dropped when the migration is reverted.

// database/migrations/1669833880587-create-users.ts
import { MigrationInterface, QueryRunner, Table } from 'typeorm';
export class CreateUsers1669833880587 implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.createTable(
      new Table({
        name: 'users',
        columns: [
          {
            name: 'id',
            type: 'uuid',
            default: 'uuid_generate_v4()',
            generationStrategy: 'uuid',
            isGenerated: true,
            isPrimary: true
          },
          {
            name: 'first_name',
            type: 'varchar'
          }
        ]
      })
    );
  }
  public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.dropTable('users');
  }
}

Scripts for running and reverting the migrations require a separate DataSource configuration, the migrations table name is migrations in this case. Running a migration adds a new row with the migration name while reverting removes it.

// config/ormconfig-migration.ts
import 'dotenv/config';
import * as path from 'path';
import { DataSource } from 'typeorm';
const config = new DataSource({
  type: 'postgres',
  host: process.env.DATABASE_HOSTNAME,
  port: Number(process.env.DATABASE_PORT),
  username: process.env.DATABASE_USERNAME,
  password: process.env.DATABASE_PASSWORD,
  database: process.env.DATABASE_NAME,
  entities: [path.resolve(`${__dirname}/../../**/**.entity{.ts,.js}`)],
  migrations: [
    path.resolve(`${__dirname}/../../../database/migrations/*{.ts,.js}`)
  ],
  migrationsTableName: 'migrations',
  logging: true,
  synchronize: false
});
export default config;

Seeder is a type of migration, seeders are handled with the following scripts for generation, running, and reverting.

// package.json
{
  "scripts": {
    "seed:generate": "npm run typeorm -- migration:create",
    "seed": "npm run typeorm -- migration:run -d src/common/config/ormconfig-seeder.ts",
    "seed:down": "npm run typeorm -- migration:revert -d src/common/config/ormconfig-seeder.ts"
  }
}

A new seeder is generated at the provided path with the following command. The filename of it is in the format <TIMESTAMP>-<SEEDER_NAME>.ts.

npm run seeder:generate database/seeders/<SEEDER_NAME>

Here is the example for the seeder which inserts some data. A table data is removed when the seeder is reverted.

// database/seeders/1669834539569-add-users.ts
import { UsersEntity } from '../../src/modules/users/users.entity';
import { MigrationInterface, QueryRunner } from 'typeorm';
export class AddUsers1669834539569 implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.manager.insert(UsersEntity, [
      {
        firstName: 'tester'
      }
    ]);
  }
  public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.manager.clear(UsersEntity);
  }
}

Scripts for running and reverting the seeders require a separate DataSource configuration, the seeders table name is seeders in this case. Running a seeder adds a new row with the seeder name while reverting removes it.

// config/ormconfig-seeder.ts
import 'dotenv/config';
import * as path from 'path';
import { DataSource } from 'typeorm';
const config = new DataSource({
  type: 'postgres',
  host: process.env.DATABASE_HOSTNAME,
  port: Number(process.env.DATABASE_PORT),
  username: process.env.DATABASE_USERNAME,
  password: process.env.DATABASE_PASSWORD,
  database: process.env.DATABASE_NAME,
  entities: [path.resolve(`${__dirname}/../../**/**.entity{.ts,.js}`)],
  migrations: [
    path.resolve(`${__dirname}/../../../database/seeders/*{.ts,.js}`)
  ],
  migrationsTableName: 'seeders',
  logging: true,
  synchronize: false
});
export default config;

Entities

Entities are specified with their columns and Entity decorator.

// users.entity.ts
import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';
@Entity({ name: 'users' })
export class UsersEntity {
  @PrimaryGeneratedColumn('uuid')
  public id: string;
  @Column({ name: 'first_name' })
  public firstName: string;
}

Entities should be registered with forFeature method.

// users.module
@Module({
  imports: [TypeOrmModule.forFeature([UsersEntity])],
  // ...
})
export class UsersModule {}

Custom repositories

Custom repositories extend the base repository class and enrich it with several additional methods.

// users.repository.ts
@Injectable()
export class UsersRepository extends Repository<UsersEntity> {
  constructor(private dataSource: DataSource) {
    super(UsersEntity, dataSource.createEntityManager());
  }
  async getById(id: string) {
    return this.findOne({ where: { id } });
  }
  // ...
}

Custom repositories should be registered as a provider.

// users.module
@Module({
  // ...
  providers: [UsersService, UsersRepository],
  // ...
})
export class UsersModule {}

Testing custom repositories

Testing custom repositories (NestJS/TypeORM) post covers more details about the unit and integration testing.

Transactions

typeorm-transactional library uses CLS (Continuation Local Storage) to handle and propagate transactions between different repositories and service methods.

@Injectable()
export class PostService {
  constructor(
    private readonly authorRepository: AuthorRepository,
    private readonly postRepository: PostRepository
  ) {}
  @Transactional() // will open a transaction if one doesn't already exist
  async createPost(authorUsername: string, message: string): Promise<Post> {
    const author = await this.authorRepository.create({
      username: authorUsername
    });
    return this.postRepository.save({ message, author_id: author.id });
  }
}

Initialization of transactional context should happen before starting the app.

// main.ts
async function bootstrap(): Promise<void> {
  initializeTransactionalContext();
  // ...
}

DataSource instance should be added to the transactional context.

const typeOrmConfig = {
  // ...
  dataSourceFactory: async (options) =>
    addTransactionalDataSource(new DataSource(options)).initialize()
};

Boilerplate

Here is the link to the boilerplate I use for the development. It contains the examples mentioned above with more details.

Gatsby blog as PWA (Progressive Web App)

November 26, 2022

Starting with some of the benefits, installed PWAs can bring more user engagement and conversions. On the user side, it brings the possibility to read posts offline. Progressive Web App 101 post covers more details about PWAs.

Prerequisites

bootstrapped Gatsby blog
installed manifest (gatsby-plugin-manifest) and offline (gatsby-plugin-offline) plugins

Setup

Add plugin configurations to the Gatsby configuration file. The manifest plugin should be loaded before the offline plugin.

Prepare the app icon in 512x512 pixels, and the manifest plugin will generate the icons in all the necessary dimensions. PWA usage can be logged with the UTM link in start_url property.

Runtime caching for static resources (JavaScript, CSS, and page data JSON files) is set to network-first caching, so it retrieves the latest changes before showing them to the user. In case of issues with caching in a local environment, an offline plugin can be disabled.

// gatsby-config.js
const plugins = [
  // ...
  {
    resolve: `gatsby-plugin-manifest`,
    options: {
      name: `app name`,
      short_name: `app name`,
      start_url: `/?utm_source=pwa&utm_medium=pwa&utm_campaign=pwa`,
      background_color: `#FFF`,
      theme_color: `#2F3C7E`,
      display: `standalone`,
      icon: `src/assets/icon.png`
    }
  }
];
if (process.env.NODE_ENV !== 'development') {
  plugins.push({
    resolve: `gatsby-plugin-offline`,
    options: {
      workboxConfig: {
        runtimeCaching: [
          {
            urlPattern: /(\.js$|\.css$|static\/)/,
            handler: `NetworkFirst`
          },
          {
            urlPattern: /^https?:.*\/page-data\/.*\.json/,
            handler: `NetworkFirst`
          },
          {
            urlPattern: /^https?:.*\.(png|jpg|jpeg|webp|svg|gif|tiff|js|woff|woff2|json|css)$/,
            handler: `StaleWhileRevalidate`
          },
          {
            urlPattern: /^https?:\/\/fonts\.googleapis\.com\/css/,
            handler: `StaleWhileRevalidate`
          }
        ]
      }
    }
  });
}
module.exports = {
  // ...
  plugins
};

Service worker updates can also be detected. For a better user experience, a user should approve refreshing the page before updating it to the latest version.

// gatsby-browser.js
exports.onServiceWorkerUpdateReady = () => {
  const shouldReload = window.confirm(
    'This website has been updated. Reload to display the latest version?'
  );
  if (shouldReload) {
    window.location.href = window.location.href.replace(/#.*$/, '');
  }
};
exports.onRouteUpdate = async () => {
  if (!navigator) {
    console.log('Navigator is not defined, skipping service worker registration...');
    return;
  }
  if (!navigator.serviceWorker) {
    console.log('Service worker is not supported, skipping registration...');
    return;
  }
  try {
    const registration = await navigator.serviceWorker.register('/sw.js');
    await registration.update();
  } catch (error) {
    console.error('Service worker registration failed', error);
  }
};

Documenting JavaScript code with JSDoc

November 24, 2022

JSDoc provides adding types to the JavaScript codebase with appropriate conventions inside comments so different IDEs like Visual Studio Code can recognize defined types, show them and make coding easier with auto-completion. Definitions are put inside /** */ comments.

Examples

Custom types can be defined with @typedef and @property tags. Every property has a type and if the property is optional, its name is put between square brackets, and a description can be included after the property name. Global types should be defined in *.jsdoc.js files so they can be used in multiple files without importing. * represents any type.

/**
 * @typedef {object} CollectionItem
 * @property {string} [collectionName] - collection name is optional string field
 * @property {boolean} isRevealed - reveal status
 * @property {number} floorPrice - floor price
 * @property {?string} username - username is a nullable field
 * @property {Array.<number>} prices - prices array
 * @property {Array.<string>} [buyers] - optional buyers array
 * @property {Array.<Object<string, *>>} data - some data
 */

Classes are auto recognized so @class and @constructor tags can be omitted.

/**
 * Scraper for websites
 */
class Scraper {
  /**
   * Create scraper
   * @param {string} url - website's URL
   */
  constructor(url) {
    this.url = url;
  }
  // ...
}

Comments starting with the description can omit @description tag. Function parameters and function return types can be defined with @param and @returns tags. Multiple return types can be handled with | operator. Deprecated parts of the codebase can be annotated with @deprecated tag.

/**
 * Gets prices list
 * @private
 * @param {Array.<number>} prices - prices array
 * @returns {string|undefined}
 */
const getPricesList = (prices) => {
  if (prices.length > 0) return prices.join(',');
};
/**
 * Get data from the API
 * @deprecated
 * @returns {Promise<CollectionItem>}
*/
const getData = async () => {
  // ...
};

Variable types can be documented with @type tags and constants can utilize @const tags.

/**
 * Counter for the requests
 * @type {number}
 */
let counter;
/**
 * HTTP timeout in milliseconds
 * @const {number}
*/
const HTTP_TIMEOUT_MS = 3000;

Enums can be documented with @enum and @readonly tags.

/**
 * Some states
 * @readonly
 * @enum {string}
 */
const state = {
  STARTED: 'STARTED',
  IN_PROGRESS: 'IN_PROGRESS',
  FINISHED: 'FINISHED',
};

Docs validation

Linter can validate the docs. Add the following package and update the linter configuration file.

npm i -D eslint-plugin-jsdoc

// .eslintrc.js
module.exports = {
  extends: ['plugin:jsdoc/recommended'],
};

Run the linter and it will show warnings if something has to be improved.

Generating the docs overview

Run the following command to recursively generate the HTML files with the docs overview, including the README.md and package.json content. Symbols marked with @private tags will be skipped.

npx jsdoc src -r --destination docs --readme ./README.md --package ./package.json

This command can be included in the CI/CD pipeline, it depends on the needs of the project.

Deploying Node.js apps to Fly.io

November 17, 2022

This post covers main notes from setting up the Fly.io CLI tool to CI/CD pipeline with Github actions . Prerequisites Run the following…

Android app development with React Native

November 10, 2022

This post covers the main notes needed, from bootstrapping the app to publishing to the Play store. Prerequisites experience with React…

Telegram bots with Node.js

November 7, 2022

Telegram bots, besides regular chatbots, can also be used as "dashboards". Authentication is already there, as well as the UI to send…

Timeout with Fetch API

November 2, 2022

Setting up a timeout for HTTP requests can prevent the connection from hanging forever, waiting for the response. It can be set on the client side to improve user experience, and on the server side to improve inter-service communication. Fetch API is fully available in Node as well from version 18.

AbortController can be utilized to set up timeouts. Instantiated abort controller has a signal property which represents reference to its associated AbortSignal object. Abort signal object is used as a signal parameter in the request with Fetch API, so HTTP request is aborted when abort method is called.

const HTTP_TIMEOUT = 3000;
const URL = 'https://www.google.com:81';
(async () => {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), HTTP_TIMEOUT);
  try {
    const response = await fetch(URL, {
      signal: controller.signal
    }).then((res) => res.json());
    console.log(response);
  } catch (error) {
    console.error(error);
  } finally {
    clearTimeout(timeoutId);
  }
})();

Splash screen with React Native

October 30, 2022

A splash screen is the first thing user sees after opening the app, and it usually shows an app logo with optional animations. This post covers setup for Android devices and iOS setup will be covered additionally.

Prerequisites

installed Android studio
bootstrapped app
react-native-splash-screen package installed

npx react-native init SplashScreenApp
cd SplashScreenApp
npm i react-native-splash-screen

JavaScript setup

Hide the splash screen when the app is ready

// App.js
// ...
useEffect(() => SplashScreen.hide(), []);
// ...

Native setup

Extending MainActivity class with onCreate method

// android/app/src/main/java/com/splashscreenapp/MainActivity.java
import org.devio.rn.splashscreen.SplashScreen;
import android.os.Bundle;
// ...
@Override
protected void onCreate(Bundle savedInstanceState) {
  SplashScreen.show(this, R.style.SplashTheme, true);
  super.onCreate(savedInstanceState);
}
// ...

Adding splash screen activity with the theme into the Android manifest

file: android/app/src/main/AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
  package="com.splashscreenapp">
  <uses-permission android:name="android.permission.INTERNET" />
  <application
    android:name=".MainApplication"
    android:label="@string/app_name"
    android:icon="@mipmap/ic_launcher"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:allowBackup="false"
    android:theme="@style/AppTheme">
    <activity
      android:name=".SplashActivity"
      android:theme="@style/SplashTheme"
      android:label="@string/app_name"
      android:exported="true">
      <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
    </activity>
    <activity
      android:name=".MainActivity"
      android:label="@string/app_name"
      android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
      android:windowSoftInputMode="adjustResize"
      android:exported="true"/>
    <activity android:name="com.facebook.react.devsupport.DevSettingsActivity" />
  </application>
</manifest>

Implementing SplashActivity class

// android/app/src/main/java/SplashActivity.java
package com.splashscreenapp;
import android.content.Intent;
import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
public class SplashActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Intent intent = new Intent(this, MainActivity.class);
    startActivity(intent);
    finish();
  }
}

Themes setup

file: android/app/src/main/res/values/styles.xml

<resources>
  <style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    <item name="android:statusBarColor">@color/theme_bg</item>
    <item name="android:windowBackground">@drawable/background_splash</item>
  </style>
  <style name="SplashTheme" parent="Theme.AppCompat.Light.NoActionBar">
    <item name="android:background">@drawable/background_splash</item>
    <item name="android:windowDisablePreview">true</item>
    <item name="colorPrimaryDark">@color/theme_bg</item>
  </style>
</resources>

Colors setup

file: android/app/src/main/res/values/colors.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <color name="theme_bg">#2F3C7E</color>
</resources>

Adding config for background splash drawable

file: android/app/src/main/res/drawable/background_splash.xml

<?xml version="1.0" encoding="utf-8"?>
<layer-list xmlns:android="http://schemas.android.com/apk/res/android" android:opacity="opaque">
  <item android:drawable="@color/theme_bg"/>
  <item
    android:width="300dp"
    android:height="300dp"
    android:drawable="@mipmap/splash_icon"
    android:gravity="center" />
</layer-list>

Adding layout

file: android/app/src/main/res/layout/launch_screen.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="@drawable/background_splash"
  android:orientation="vertical">
</LinearLayout>

Images for splash screen

App Icon Generator can be used for generating the images. Open the Image Sets tab, choose 4X design base size, insert an image and generate corresponding images for the splash screen. Downloaded images should be stored in mipmap (android/app/src/main/res/mipmap-*hdpi/splash_icon.png) folders.

Demo

Run the following commands

npx react-native start
npx react-native run-android

Push notifications with Firebase

May 29, 2022

Push notifications are a great alternative to email notifications. There is no need for a verification step, UX is improved, and user engagement with the app is increased. This post covers both front-end and back-end setups.

Requirements for the push notifications

firebase package installed
Created Firebase project
Firebase configuration can be found on Project Overview → Project settings → General → Your apps
Public Vapid key can be found on Project Overview → Project settings → Cloud Messaging → Web Push certificates (used on the front-end)
Firebase messaging service worker
Project ID can be found on Project Overview → Project settings → General tab
Server key for sending the push notifications (used on the back end)
HTTPS connection (localhost for local development)

Front-end setup

Firebase messaging service worker

The following service worker should be registered for handling background notifications. A custom notificationclick handler should be implemented before importing firebase libraries. The below implementation opens a new window with the defined URL if it is not already open. Firebase automatically checks for service workers at /firebase-messaging-sw.js, so it should be publicly available.

// /firebase-messaging-sw.js
/* eslint-disable no-unused-vars */
self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  const DEFAULT_URL = '<URL>';
  const url =
    event.notification?.data?.FCM_MSG?.notification?.click_action ||
    DEFAULT_URL;
  event.waitUntil(
    clients.matchAll({ type: 'window' }).then((clientsArray) => {
      const hadWindowToFocus = clientsArray.some((windowClient) =>
        windowClient.url === url ? (windowClient.focus(), true) : false
      );
      if (!hadWindowToFocus)
        clients
          .openWindow(url)
          .then((windowClient) => (windowClient ? windowClient.focus() : null));
    })
  );
});
importScripts('https://www.gstatic.com/firebasejs/9.19.1/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/9.19.1/firebase-messaging-compat.js');
const firebaseApp = initializeApp({
  apiKey: 'xxxxxx',
  authDomain: 'xxxxxx',
  projectId: 'xxxxxx',
  storageBucket: 'xxxxxx',
  messagingSenderId: 'xxxxxx',
  appId: 'xxxxxx',
  measurementId: 'xxxxxx'
});
const messaging = getMessaging(firebaseApp);

Helper functions

`getToken`

generates a unique registration token for the browser or gets an already generated token
requests permission to receive push notifications
triggers the Firebase messaging service worker

There are multiple types of errors as response:

code messaging/permission-blocked - user blocks the notifications
code messaging/unsupported-browser - user's browser doesn't support the APIs required to use the Firebase SDK
code messaging/failed-service-worker-registration - there's an issue with the Firebase messaging service worker

The access token is invalidated when a user manually blocks the notifications in the browser settings.

`isSupported`

checks if all required APIs for push notifications are supported
returns Promise<boolean>

It should be used in useEffect hooks.

import { isSupported } from 'firebase/messaging';
// ...
useEffect(() => {
  isSupported()
    .then((isAvailable) => {
      if (isAvailable) {
        // ...
      }
    })
    .catch(console.error);
}, []);
// ...

`initializeApp`

should be called before the app starts

import { initializeApp } from 'firebase/app';
import { getMessaging, getToken } from 'firebase/messaging';
import { firebaseConfig } from 'constants/config';
export const initializeFirebase = () => initializeApp(firebaseConfig);
export const getTokenForPushNotifications = async () => {
  const messaging = getMessaging();
  const token = await getToken(messaging, {
    vapidKey: process.env.NEXT_PUBLIC_VAPID_KEY
  });
  return token;
};

Back-end setup

Server keys

The server key for API v1 can be derived from the service account key JSON file. In that case, the JSON file should be encoded and stored in the environment variable to prevent exposing credentials in the repository codebase. The service account key JSON file can be downloaded by clicking Generate new private key on the Project Overview → Project settings → Service accounts tab.

import * as serviceAccountKey from './service-account-key.json';
const encodedServiceAccountKey = Buffer.from(
  JSON.stringify(serviceAccountKey)
).toString('base64');
process.env.SERVICE_ACCOUNT_KEY = encodedServiceAccountKey;

import 'dotenv/config';
import * as googleAuth from 'google-auth-library';
(async () => {
  const serviceAccountKeyEncoded = process.env.SERVICE_ACCOUNT_KEY;
  const serviceAccountKeyDecoded = JSON.parse(
    Buffer.from(serviceAccountKeyEncoded, 'base64').toString('ascii')
  );
  const jwt = new googleAuth.JWT(
    serviceAccountKeyDecoded.client_email,
    null,
    serviceAccountKeyDecoded.private_key,
    ['https://www.googleapis.com/auth/firebase.messaging'],
    null
  );
  const tokens = await jwt.authorize();
  const authorizationHeader = `Bearer ${tokens.access_token}`;
  console.log(authorizationHeader);
})();

Manually sending the push notification

The icon URL should be covered with HTTPS, so the notification correctly shows it.

API v1

// ...
try {
  const response = await axios.post(
    `https://fcm.googleapis.com/v1/projects/${projectId}/messages:send`,
    {
      message: {
        notification: {
          title: 'Push notifications with Firebase',
          body: 'Push notifications with Firebase body'
        },
        webpush: {
          fcmOptions: {
            link: 'http://localhost:3000'
          },
          notification: {
            icon: 'https://picsum.photos/200'
          }
        },
        token: registrationToken
      }
    },
    {
      headers: {
        Authorization: authorizationHeader
      }
    }
  );
  console.log(response.data);
} catch (error) {
  console.error(error?.response?.data?.error);
}
// ...

A successful response returns an object with name key, which presents the notification id in the format projects/{project_id}/messages/{message_id}.

There are multiple types of errors in the response:

code 400 - request body is not valid
code 401 - the derived token is expired
code 404 - registration token was not found

Demo

Here is the link to the demo with the codebase.

State management with Next.js and React

May 15, 2022

The global state can be helpful when components share some common parts. Also, some parts can stay persistent (in local storage) and be used in the following user's session. React provides a native way to handle state management using context with the hooks.

Usage

// ...
import { useAppContext } from "context";
import { UPDATE_FEATURE_ACTIVATION } from "context/constants";
export function CustomComponent() {
  const { state, dispatch } = useAppContext();
  // get value from the store
  console.log(state.isFeatureActivated);
  // dispatch action to change the state
  dispatch({ type: UPDATE_FEATURE_ACTIVATION, payload: { isFeatureActivated: true } });
  // ...
}

Context setup

// context/index.jsx
import PropTypes from "prop-types";
import React, {
  createContext,
  useContext,
  useEffect,
  useMemo,
  useReducer,
} from "react";
import { getItem, setItem, STATE_KEY } from "utils/local-storage";
import { INITIALIZE_STORE } from "./constants";
import { appReducer, initialState } from "./reducer";
const appContext = createContext(initialState);
export function AppWrapper({ children }) {
  const [state, dispatch] = useReducer(appReducer, initialState);
  const contextValue = useMemo(() => {
    return { state, dispatch };
  }, [state, dispatch]);
  useEffect(() => {
    const stateItem = getItem(STATE_KEY);
    if (!stateItem) return;
    const parsedState = JSON.parse(stateItem);
    const updatedState = {
      ...initialState,
      // persistent state
      isFeatureActivated: parsedState.isFeatureActivated,
    };
    dispatch({
      type: INITIALIZE_STORE,
      payload: updatedState,
    });
  }, []);
  useEffect(() => {
    if (state !== initialState) {
      setItem(STATE_KEY, JSON.stringify(state));
    }
  }, [state]);
  return (
    <appContext.Provider value={contextValue}>{children}</appContext.Provider>
  );
}
AppWrapper.propTypes = {
  children: PropTypes.oneOfType([PropTypes.array, PropTypes.object]).isRequired,
};
export function useAppContext() {
  return useContext(appContext);
}

Reducer with actions

// context/reducer.js
import { INITIALIZE_STORE, UPDATE_FEATURE_ACTIVATION } from "./constants";
export const initialState = {
  isFeatureActivated: false,
};
export const appReducer = (state, action) => {
  switch (action.type) {
    case INITIALIZE_STORE: {
      return action.payload;
    }
    case UPDATE_FEATURE_ACTIVATION: {
      return {
        ...state,
        isFeatureActivated: action.payload.isFeatureActivated,
      };
    }
    default:
      return state;
  }
};

Wrapper around the app

// _app.jsx
import { AppWrapper } from "context";
function App({ Component, pageProps }) {
  // ...
  return (
    <AppWrapper>
      <Component {...pageProps} />
    </AppWrapper>
  );
}

Constants

// context/constants.js
export const INITIALIZE_STORE = "INITIALIZE_STORE";
export const UPDATE_FEATURE_ACTIVATION = "UPDATE_FEATURE_ACTIVATION";

JSON logging bash scripts

March 18, 2022

Logs are usually streamed to the standard output in JSON format so logging aggregators (Graylog, e.g.) can collect and adequately parse them.

The following example shows how bash script output can be formatted with the message, log levels, and timestamp. Error logs are streamed into a temporary file, formatted, and redirected to the standard output.

#!/usr/bin/env bash
declare -A log_levels=( [FATAL]=0 [ERROR]=3 [WARNING]=4 [INFO]=6 [DEBUG]=7)
json_logger() {
  log_level=$1
  message=$2
  level=${log_levels[$log_level]}
  timestamp=$(date --iso-8601=seconds)
  jq --raw-input --compact-output \
    '{
      "level": '$level',
      "timestamp": "'$timestamp'",
      "message": .
    }'
}
{
  set -e
  echo $? 1>&2
  echo "Finished"
} 2>/tmp/stderr.log | json_logger "INFO"
cat /tmp/stderr.log | json_logger "ERROR"

Sending e-mails in different environments

March 8, 2022

For local testing or testing in general, there is no need to send e-mails to real e-mail addresses. Mailtrap service can preview the e-mails for sending. The inbox page can show credentials (username and password). A list of inboxes is available at Projects page.

Use other services to send e-mails in a production environment (Sendgrid, e.g.). Create SendGrid API key at API keys page.

require('dotenv/config');
const nodemailer = require('nodemailer');
(async () => {
  const emailConfiguration = {
    auth: {
      user: process.env.EMAIL_USERNAME, // 'apikey' for Sendgrid
      pass: process.env.EMAIL_PASSWORD
    },
    host: process.env.EMAIL_HOST, // 'smtp.mailtrap.io' for Mailtrap, 'smtp.sendgrid.net' for Sendgrid
    port: process.env.EMAIL_PORT, // 2525 for Mailtrap, 465 for Sendgrid
    secure: process.env.EMAIL_SECURE // true for Sendgrid
  };
  const transport = nodemailer.createTransport(emailConfiguration);
  const info = await transport.sendMail({
    from: '"Sender" <sender@example.com>',
    to: 'recipient1@example.com, recipient2@example.com',
    subject: 'Subject',
    text: 'Text',
    html: '<b>Text</b>'
  });
  console.log('Message sent: %s', info.messageId);
})();

Chronoblog (Gatsby) theme with RSS feed

March 7, 2022

Chronoblog is one of the Gatsby blogging themes. RSS feed can be used to get the latest posts for Github actions, dev.to, etc. The following steps can easily add it. Use a similar approach for other Gatsby themes.

Initial setup

Run the following commands to clone the repository and install the required packages.

npx gatsby new chronoblog-site https://github.com/Chronoblog/gatsby-starter-chronoblog
cd chronoblog-site
npm i gatsby-plugin-feed@2 gatsby-transformer-remark@3 gatsby-source-filesystem

GraphQL setup

Populate GraphQL fields to avoid null errors. Add canonical_url: http://example.com to content → links → frontmatter-placeholder → index.md file.

Gatsby config

Add plugin configurations in gatsby-config.js. Draft content, links, and placeholder post are skipped.

module.exports = {
  // ...
  plugins: [
    // ...
    {
      resolve: `gatsby-plugin-feed`,
      options: {
        query: `
          {
            site {
              siteMetadata {
                title
                description
                siteUrl
                site_url: siteUrl
              }
            }
          }
        `,
        feeds: [
          {
            serialize: ({ query: { site, allMarkdownRemark } }) => {
              return allMarkdownRemark.edges.map(edge => {
                return Object.assign({}, edge.node.frontmatter, {
                  description: edge.node.excerpt,
                  date: edge.node.frontmatter.date,
                  url: edge.node.frontmatter.canonical_url || edge.node.frontmatter.url,
                  guid: edge.node.frontmatter.canonical_url || edge.node.frontmatter.url,
                  custom_elements: [{ "content:encoded": edge.node.html }],
                })
              })
            },
            query: `
              {
                allMarkdownRemark(
                  filter: { 
                    frontmatter: {
                      draft: { ne: true },
                      link: { eq: null },
                      title: { ne: "Ghost Post" }
                    },
                  },
                  sort: { order: DESC, fields: [frontmatter___date] },
                ) {
                  edges {
                    node {
                      excerpt
                      html
                      fields { slug }
                      frontmatter {
                        title
                        canonical_url
                        date
                      }
                    }
                  }
                }
              }
            `,
            output: "/rss.xml",
            title: "RSS Feed",
          },
        ],
      },
    },
    {
      resolve: `gatsby-transformer-remark`
    },
  ],
  // ...
};

Gatsby node setup

Implement onCreateNode function in gatsby-node.js file

const { createFilePath } = require(`gatsby-source-filesystem`);
exports.onCreateNode = ({ node, actions, getNode }) => {
  const { createNodeField } = actions
  if (node.internal.type === `MarkdownRemark`) {
    const value = createFilePath({ node, getNode })
    createNodeField({
      name: `slug`,
      node,
      value,
    })
  }
}

Npm scripts setup

Add serve script in package.json

{
  // ...
  "scripts": {
    // ...
    "serve": "gatsby serve"
  }
}

Demo

Run npm run build && npm run serve. RSS feed should be populated on http://localhost:9000/rss.xml page.

Next.js app in production

March 6, 2022

Consider the following things when the Next.js app is running in production.

Error tracking and alerting

Sentry issues show the error stack trace, device, operating system, and browser information. The project dashboard shows an unhandled exception once it's thrown. Run the following commands for integration with the Next.js app.

npm i @sentry/nextjs
npx @sentry/wizard -i nextjs

Intl API is not supported in some browsers. Cover it with a fallback.
localStorage API is not available when cookies are blocked. Cover it with a fallback.

Progressive Web Apps 101

March 5, 2022

Progressive Web Apps bring some advantages over native mobile apps

automatic updates can be implemented
the installed app takes less memory
installable on phones, tablets, desktops

Prerequisites for installation

web app is running over an HTTPS connection
service worker is registered
web app manifest (manifest.json) is included

Service worker

Read more about it on Caching with service worker and Workbox

Manifest

Following fields can be included

name is a full name used when the app is installed
short_name is a shorter version of the name that is shown when there is insufficient space to display the full name
background_color is used on a splash screen
description is shown on an installation pop-up
display customizes which browser UI is shown when the app is launched (standalone, fullscreen, minimal-ui, browser)
icons is a list of icons for the browser used in different places (home screen, app launcher, etc.)
scope specifies the navigation scope of the PWA. It should start with the URL from start_url value. If the user navigates outside the scope, PWA won't be open from external URLs
screenshots is a list of screenshots shown on the installation pop-up
start_url is a relative URL of the app which is loaded when the installed app is launched. PWA usage can be tracked by adding UTM parameters within the URL.
theme_color sets the color of the toolbar, it should match the meta theme color specified in the document head

Description and screenshots are shown only on mobile phones.

{
  "name": "App name",
  "short_name": "App short name",
  "background_color": "#ffffff",
  "description": "App description",
  "display": "standalone",
  "icons": [
    {
      "src": "icons/icon-128x128.png",
      "sizes": "128x128",
      "type": "image/png"
    },
    {
      "src": "icons/icon-144x144.png",
      "sizes": "144x144",
      "type": "image/png"
    },
    {
      "src": "icons/icon-152x152.png",
      "sizes": "152x152",
      "type": "image/png"
    },
    {
      "src": "icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "scope": "/app",
  "screenshots": [{
    "src": "screenshots/main.jpg",
    "sizes": "1080x2400",
    "type": "image/jpg"
  }],
  "start_url": "/app?utm_source=pwa&utm_medium=pwa&utm_campaign=pwa",
  "theme_color": "#3366cc"
}

Manifest file should be included via link tag

<link rel="manifest" href="/manifest.json">

In-app installation experience

It can be implemented on Google Chrome and Edge.

listen for the beforeinstallprompt event
save beforeinstallprompt event so it can be used to trigger the installation
provide a button to start the in-app installation flow

let deferredPrompt;
let installable = false;
window.addEventListener("beforeinstallprompt", (event) => {
  event.preventDefault();
  deferredPrompt = event;
  installable = true;
  document.getElementById("installable-btn").innerHTML = "Install";
});
window.addEventListener("appinstalled", () => {
  installable = false;
});
document.getElementById("installable-btn").addEventListener("click", () => {
  if (installable) {
    deferredPrompt.prompt();
    deferredPrompt.userChoice.then((choiceResult) => {
      if (choiceResult.outcome === "accepted") {
        document.getElementById("installable-btn").innerHTML = "click!";
      }
    });
  } else {
    alert("clicked!");
  }
});

Notes

chrome://webapks page on mobile phones shows the list of installed PWAs with their details. Last Update Check Time is useful for checking when the manifest file was updated. The app is updated once a day if there are some manifest changes.

Example

A working example is available at https://github.com/zsevic/pwa-starter

Integrating Next.js app with Google analytics 4

February 4, 2022

Google analytics helps get more insights into app usage.

Prerequisites

Google analytics product is already set up, tracking ID is needed
Next.js app should be bootstrapped
react-ga4 package is installed

Analytics initialization

Analytics should be initialized inside pages/_app.js file.

import ReactGA from "react-ga4";
// ...
if (isEnvironment("production")) {
  ReactGA.initialize(ANALYTICS_TRACKING_ID);
}

Tracking events (clicks, e.g.)

// ...
export function trackEvent(category, label, action = "click") {
  if (isEnvironment("production")) {
    ReactGA.event({
      action,
      category,
      label,
    });
  }
}
// ...
<Button onClick={() => trackEvent("category", "label")}>

⬈ FlatMe

https://flat-me.com

Web app for finding apartments for rent and sale in Belgrade

⬈ Apeiner

https://t.me/apeiner_bot

Telegram bot that tracks Ethereum NFTs insights

⬈ Hackathonist

https://sevic.dev/hackathonist

List of upcoming and recent hackathons in Serbia

⬈ NestJS boilerplate

https://sevic.dev/nestjs-starter?ref=projects

Minimal NestJS boilerplate

⬈ orbit-pdf

https://npmjs.com/package/@zsevic/orbit-pdf

CLI tool for converting Orbit HTML resume to PDF

⬈ Otvorene granice

https://open-borders.vercel.app

NLP classifier for open borders (related to COVID-19 restrictions)

2021

Automate finding an apartment for rent or sale

December 28, 2021

I have recently automated the process of finding apartments for rent or sale. Tech-stack I used for automation API includes Node.js…

Redis as custom storage for NestJS rate limiter

September 14, 2021

A rate limiter is a standard protection technique against brute force and DDoS attacks. NestJS provides a module for it, and the default storage is in-memory. Custom storage, Redis in this case, should be injected inside ThrottlerModule configuration.

Configuration

The configuration should contain

TTL (time to live) in seconds
maximum number of requests within TTL
Redis URL

// app.module.ts
import { APP_GUARD } from '@nestjs/core';
import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
import { ThrottlerStorageRedisService } from 'nestjs-throttler-storage-redis';
// ...
@Module({
  imports: [
    ThrottlerModule.forRootAsync({
      inject: [CustomConfigService],
      useFactory: (configService: CustomConfigService) => ({
        ttl: configService.THROTTLER_TTL_SECONDS,
        limit: configService.THROTTLER_LIMIT,
        storage: new ThrottlerStorageRedisService(configService.REDIS_URL),
      }),
    }),
    // ...
  ],
})
export class AppModule {}

API endpoints setup

Binding the throttler guard can be done in multiple ways.

guard is bound globally for every API endpoint.

// app.module
import { ThrottlerGuard } from '@nestjs/throttler';
// ...
@Module({
  // ...
  providers: [{
    provide: APP_GUARD,
    useClass: ThrottlerGuard,
  }],
})
export class AppModule {}

global guard is overridden for the specific API endpoint with the Throttle decorator.

import { Throttle } from '@nestjs/throttler';
// ...
@Controller('users')
export class UsersController {
  @Throttle(USERS_THROTTLER_LIMIT, USERS_THROTTLER_TTL_SECONDS)
  @Get()
  async getUsers() {}
}

global guard is skipped for the specific API endpoint with the SkipThrottle decorator.

import { SkipThrottle } from '@nestjs/throttler';
// ...
@Controller('posts')
export class PostsController {
  @SkipThrottle()
  @Get()
  async getPosts() {}
}

Postgres and Redis container services for e2e tests in Github actions

September 8, 2021

End-to-end tests should use a real database connection, and provisioning container service for the Postgres database can be automated using Github actions. The environment variable for the connection string for the newly created database can be set in the step for running e2e tests. The same goes for the Redis instance.

# ...
jobs:
  build:
    # Container must run in Linux-based operating systems
    runs-on: ubuntu-latest
    # Image from Docker hub
    container: node:18.12.1-alpine3.15
    # ...
    strategy:
      matrix:
        # ...
        database-name:
          - e2e-testing-db
        database-user:
          - username
        database-password:
          - password
        database-host:
          - postgres
        database-port:
          - 5432
        redis-host:
          - redis
        redis-port:
          - 6379
    services:
      postgres:
        image: postgres:latest
        env:
          POSTGRES_DB: ${{ matrix.database-name }}
          POSTGRES_USER: ${{ matrix.database-user }}
          POSTGRES_PASSWORD: ${{ matrix.database-password }}
        ports:
          - ${{ matrix.database-port }}:${{ matrix.database-port }}
        # Set health checks to wait until postgres has started
        options: --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
      redis:
        image: redis
        # Set health checks to wait until redis has started
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      # ...
      - run: npm run test:e2e
        env:
          DATABASE_URL: postgres://${{ matrix.database-user }}:${{ matrix.database-password }}@${{ matrix.database-host }}:${{ matrix.database-port }}/${{ matrix.database-name }}
          REDIS_URL: redis://${{ matrix.redis-host }}:${{ matrix.redis-port }}
      # ...

Further learning

GitHub actions 101

Testing custom repositories (NestJS/TypeORM)

September 5, 2021

Custom repositories extend the base repository class and enrich it with several additional methods. This post covers the unit and integration testing.

// user.repository.ts
@Injectable()
export class UserRepository extends Repository<UserEntity> {
  constructor(private dataSource: DataSource) {
    super(UserEntity, dataSource.createEntityManager());
  }
  async getById(id: string) {
    return this.findOne({ where: { id } });
  }
  // ...
}

Setup

Inject a custom repository into the service.

// user.service.ts
export class UserService {
  constructor(private readonly userRepository: UserRepository) {}
  async getById(id: string): Promise<User> {
    return this.userRepository.getById(id);
  }
  // ...
}

Pass entity class to the forFeature method.

// user.module.ts
@Module({
  imports: [
    TypeOrmModule.forFeature([UserEntity])],
    // ...
  ],
  providers: [UserService, UserRepository],
  // ...
})
export class UserModule {}

Unit testing

To properly unit-test the custom repository, mock some methods.

// user.repository.spec.ts
describe('UserRepository', () => {
  let userRepository: UserRepository;
  const dataSource = {
    createEntityManager: jest.fn()
  };
  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        UserRepository,
        {
          provide: DataSource,
          useValue: dataSource
        }
      ]
    }).compile();
    userRepository = module.get<UserRepository>(UserRepository);
  });
  describe('getById', () => {
    it('should return found user', async () => {
      const id = 'id';
      const user = {
        id
      };
      const findOneSpy = jest
        .spyOn(userRepository, 'findOne')
        .mockResolvedValue(user as UserEntity);
      const foundUser = await userRepository.getById(id);
      expect(foundUser).toEqual(user);
      expect(findOneSpy).toHaveBeenCalledWith({ where: user });
    });
  });
});

Integration testing

Integration testing is more suitable when working with databases. Read more about it on Integration testing Node.js apps post

Boilerplate

Here is the link to the boilerplate I use for the development. It contains the examples mentioned above with more details.

Spies and mocking with Jest

August 19, 2021

Besides asserting the output of the function call, unit testing includes the usage of spies and mocking. Spies are functions that let you spy on the behavior of functions called indirectly by some other code. Spy can be created by using jest.fn(). Mocking injects test values into the code during the tests. Some of the use cases will be presented below.

Async function and its resolved value can be mocked using mockResolvedValue. Another way to mock it is by using mockImplementation and providing a function as an argument.

const calculationService = {
  calculate: jest.fn()
};
jest.spyOn(calculationService, 'calculate').mockResolvedValue(value);
jest
  .spyOn(calculationService, 'calculate')
  .mockImplementation(async (a) => Promise.resolve(a));

Rejected async function can be mocked using mockRejectedValue and mockImplementation.

jest
  .spyOn(calculationService, 'calculate')
  .mockRejectedValue(new Error(errorMessage));
jest
  .spyOn(calculationService, 'calculate')
  .mockImplementation(async () => Promise.reject(new Error(errorMessage)));
await expect(calculateSomething(calculationService)).rejects.toThrowError(
  Error
);

Sync function and its return value can be mocked using mockReturnValue and mockImplementation.

jest.spyOn(calculationService, 'calculate').mockReturnValue(value);
jest.spyOn(calculationService, 'calculate').mockImplementation((a) => a);

Chained methods can be mocked using mockReturnThis.

// calculationService.get().calculate();
jest.spyOn(calculationService, 'get').mockReturnThis();

Async and sync functions called multiple times can be mocked with different values using mockResolvedValueOnce and mockReturnValueOnce, respectively, and mockImplementationOnce.

jest
  .spyOn(calculationService, 'calculate')
  .mockResolvedValueOnce(value)
  .mockResolvedValueOnce(otherValue);
jest
  .spyOn(calculationService, 'calculate')
  .mockReturnValueOnce(value)
  .mockReturnValueOnce(otherValue);
jest
  .spyOn(calculationService, 'calculate')
  .mockImplementationOnce((a) => a + 3)
  .mockImplementationOnce((a) => a + 5);

External modules can be mocked similarly to spies. For the following example, let's suppose axios package is already used in one function. The following example represents a test file where axios is mocked using jest.mock().

import axios from 'axios';
jest.mock('axios');
// within test case
axios.get.mockResolvedValue(data);

Manual mocks are resolved by writing corresponding modules in __mocks__ directory, e.g., fs/promises mock will be stored in __mocks__/fs/promises.js file. fs/promises mock will be resolved using jest.mock() in the test file.

jest.mock('fs/promises');

To assert called arguments for a mocked function, an assertion can be done using toHaveBeenCalledWith matcher.

const spy = jest.spyOn(calculationService, 'calculate');
expect(spy).toHaveBeenCalledWith(firstArgument, secondArgument);

To assert skipped call for a mocked function, an assertion can be done using not.toHaveBeenCalled matcher.

const spy = jest.spyOn(calculationService, 'calculate');
expect(spy).not.toHaveBeenCalled();

To assert called arguments for the exact call when a mocked function is called multiple times, an assertion can be done using toHaveBeenNthCalledWith matcher.

const argumentsList = [0, 1];
argumentsList.forEach((argument, index) => {
  expect(calculationService.calculate).toHaveBeenNthCalledWith(
    index + 1,
    argument
  );
});

Methods should be restored to their initial implementation before each test case.

// package.json
"jest": {
  // ...
  "restoreMocks": true
}
// ...

Demo

The demo with the mentioned examples is available at https://github.com/zsevic/jest-spies-mocking-demo repo.