DEV Community: Aakash Apoorv

🚀 Building Toy: REST API in NestJS

Aakash Apoorv — Sat, 01 Jun 2024 10:40:00 +0000

Hey everyone! 👋

🤔 Ever wondered how to start building backend applications? Let's dive into creating your first to-do app with NestJS and Node.js!

Whether you're new to backend development or just brushing up on your skills, this guide is perfect for you. We'll start with a basic To-Do application and even integrate Swagger for live API documentation. 📝

🔧 What You’ll Learn:

Set up a basic To-Do application using NestJS.
Integrate Swagger to create interactive API documentation.
Understand the basics of Node.js and NestJS frameworks.

💡 Why Build a Toy To-Do App?
It’s a fantastic exercise for beginners aiming to learn about backend development. Plus, the integration of Swagger enhances your app with interactive API documentation that can be tested directly from your browser.

Getting Started

Installing Node.js v20.9.0

Ensure you have the latest LTS version of Node.js installed using nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20.9.0
nvm use 20.9.0

Setting Up the NestJS Project

Install the NestJS CLI:

npm i -g @nestjs/cli
nest new todo-app
cd todo-app

Create a To-Do Module:

nest generate module todos
nest generate service todos
nest generate controller todos

These commands set up the basic structure for managing To-Do items.

Building the Application

Step 1: Define the To-Do Model

Create a todo.model.ts in the src/todos folder:

export class Todo {
  id: string;
  title: string;
  description?: string;
  isCompleted: boolean;
}

Step 2: Create a DTO

Define the structure for creating new To-Do items with create-todo.dto.ts:

export class CreateTodoDto {
  title: string;
  description?: string;
}

Step 3: Implement the Service

Install UUID:

npm install uuid

Services in NestJS handle business logic. Here’s how you set up todos.service.ts:

import { Injectable } from '@nestjs/common';
import { Todo } from './todo.model';
import { CreateTodoDto } from './create-todo.dto';
import { v4 as uuidv4 } from 'uuid';

@Injectable()
export class TodosService {
  private todos: Todo[] = [];

  findAll(): Todo[] {
    return this.todos;
  }

  findOne(id: string): Todo {
    return this.todos.find(todo => todo.id === id);
  }

  create(createTodoDto: CreateTodoDto): Todo {
    const todo: Todo = {
      id: uuidv4(),
      isCompleted: false,
      ...createTodoDto
    };
    this.todos.push(todo);
    return todo;
  }

  update(id: string, updateTodoDto: CreateTodoDto): Todo {
    const todo = this.findOne(id);
    if (!todo) {
      return null;
    }
    this.todos = this.todos.map(t => t.id === id ? { ...t, ...updateTodoDto } : t);
    return this.findOne(id);
  }

  delete(id: string): boolean {
    const initialLength = this.todos.length;
    this.todos = this.todos.filter(todo => todo.id !== id);
    return this.todos.length < initiallyLength;
  }
}

Step 4: Implement the Controller

Controllers manage incoming HTTP requests:

import { Controller, Get, Post, Put, Delete, Body, Param } from '@nestjs/common';
import { TodosService } from './todos.service';
import { Todo } from './todo.model';
import { CreateTodoDto } from './create-todo.dto';

@Controller('todos')
export class TodosController {
  constructor(private readonly todosService: TodosService) {}

  @Get()
  findAll(): Todo[] {
    return this.todosService.findAll();
  }

  @Post()
  create(@Body() createTodoDto: CreateTodoDto): Todo {
    return this.todosService.create(createTodoDto);
  }
}

Adding Swagger Documentation

Swagger integration in NestJS is straightforward thanks to the @nestjs/swagger module:

Install Swagger Module:

npm install @nestjs/swagger swagger-ui-express

Setup Swagger in your main application file (main.ts):

import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
import { NestFactory } from '@nestjs/core';

async function bootstrap() {
    const app = await NestFactory.create(AppModule);
    const config = new DocumentBuilder()
    .setTitle('To-Do API')
    .setDescription('The To-Do API description')
    .setVersion('1.0')
    .build();
    const document = SwaggerModule.createDocument(app, config);
    SwaggerModule.setup('api', app, document);

    await app.listen(3000);
}
bootstrap();

Running the Application

npm run start:dev

Visit http://localhost:3000/api to see your interactive Swagger API documentation, where you can also test your API endpoints.

Adding Swagger annotations

Step 5: Add Swagger annotations to To-Do Model

Enhance your data model with Swagger annotations. Modify todo.model.ts:

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

export class Todo {
    @ApiProperty({
        description: 'Unique identifier of the todo item',
        example: 'a1b2c3'
    })
    id: string;

    @ApiProperty({ description: 'Title of the todo item', example: 'Buy milk' })
    title: string;

    @ApiProperty({
        description: 'Detailed description of the todo item',
        example: 'Buy low-fat milk from the local store',
        required: false
    })
    description?: string;

    @ApiProperty({
        description: 'Indicates whether the todo item is completed',
        example: false
    })
    isCompleted: boolean;
}

Step 6: Add Swagger annotations to DTO

The CreateTodoDto also benefits from Swagger annotations, Modify create-todo.dto.ts:

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

export class CreateTodoDto {
    @ApiProperty({ description: 'Title of the todo item', example: 'Buy milk' })
    title: string;

    @ApiProperty({
        description: 'Detailed description of the todo item',
        example: 'Buy low-fat milk from the local store',
        required: false
    })
    description?: string;
}

Step 7: Add Swagger annotations to Controller

Controllers todos.controller.ts now utilize Swagger to document the API routes:

import {
    Controller,
    Get,
    Post,
    Put,
    Delete,
    Body,
    Param
} from '@nestjs/common';
import { TodosService } from './todos.service';
import { Todo } from './todo.model';
import { CreateTodoDto } from './create-todo.dto';
import { ApiTags, ApiBody, ApiResponse } from '@nestjs/swagger';

@Controller('todos')
export class TodosController {
    constructor(private readonly todosService: TodosService) {}

    @Get()
    @ApiResponse({ status: 200, description: 'Get all todos', type: [Todo] })
    findAll(): Todo[] {
        return this.todosService.findAll();
    }

    @Get(':id')
    @ApiResponse({ status: 200, description: 'Get a todo', type: Todo })
    findOne(@Param('id') id: string): Todo {
        return this.todosService.findOne(id);
    }

    @Post()
    @ApiBody({ type: CreateTodoDto })
    @ApiResponse({ status: 201, description: 'Create a new todo', type: Todo })
    create(@Body() createTodoDto: CreateTodoDto): Todo {
        return this.todosService.create(createTodoDto);
    }

    @Put(':id')
    update(
        @Param('id') id: string,
        @Body() updateTodoDto: CreateTodoDto
    ): Todo {
        return this.todosService.update(id, updateTodoDto);
    }

    @Delete(':id')
    delete(@Param('id') id: string): boolean {
        return this.todosService.delete(id);
    }
}

Running the Application Again (If stopped)

npm run start:dev

Visit http://localhost:3000/api to see your interactive Swagger API documentation with models descriptions.

Happy Coding 🚀

Quick notes on Swagger

Swagger is often mentioned alongside the OpenAPI Specification, but it's important to understand the distinction and connection between them. Swagger, initially a combination of tools for designing and documenting RESTful APIs, has evolved to be closely associated with the OpenAPI Specification.

Category	Description
Swagger Tools	Originally, Swagger included tools like Swagger UI, Swagger Editor, and Swagger Codegen for designing, documenting, and consuming RESTful APIs.
OpenAPI Specification	Initially known as the Swagger Specification, it's a standard format for describing RESTful APIs, facilitating standardized API interactions.
Relationship	In 2015, Swagger Specification was donated by SmartBear Software to the OpenAPI Initiative and renamed the OpenAPI Specification, while Swagger tools continued to support it.
Usage	Today, "Swagger" often refers to the suite of tools supporting the OpenAPI Specification, allowing developers to visualize and interact with APIs without direct access to their implementation.

🔥 Hit 'Fire' if you enjoyed this!

🚀 Building Toy ARM64 Emulator

Aakash Apoorv — Thu, 30 May 2024 16:02:16 +0000

Hey everyone! 👋

🤔 Ever wondered what it’s like to get really close to the chip level?
Dive into the world of ARM64 by building your own emulator!

Whether you’re into C++, Python, or JavaScript, I’ve got you covered with this super easy-to-follow post 🕹️.

🔧 What You’ll Learn

Get up close and personal with ARM64 architecture.
Gain hands-on experience with low-level programming and emulation.
Build an emulator in your favorite language: C++, Python, or JavaScript.

💡 Why Build an Emulator?

Learn by Doing.
Understand the ARM64 architecture.

👨‍💻 Choose Your Language:

C++: Perfect for those who love performance and speed.
Python: Great if you prefer simplicity and readability.
JavaScript: Awesome for web-based emulation and flexibility.

Features

Emulates 31 general-purpose registers (x0 to x30).
Supports basic ARM64 instructions: ldr, str, add, mul, mov, svc, and b.
Handles memory operations.
Can print the current state of registers and memory.

Methods

constructor(): Initializes the emulator with empty registers and memory, and sets the program counter (pc) to 0.
loadProgram(program): Loads a program into the emulator. The program should be a string of ARM64 assembly instructions.
run(): Runs the loaded program.
printMemory(): Prints the current state of the memory.
printRegisters(): Prints the current state of the registers.
initializeMemory(memoryInit): Initializes the emulator's memory with the given key-value pairs.

Supported Instructions

ldr: Loads a value into a register.
str: Stores a value from a register into memory.
add: Adds two register values and stores the result in a destination register.
mul: Multiplies two register values and stores the result in a destination register.
mov: Moves an immediate value into a register.
svc: (Not implemented) Placeholder for handling system calls.
b: Branches to a labeled instruction.

ARM64 Overview

ARM64 (AArch64) is a 64-bit architecture used in modern processors.
Supports a large set of registers (x0-x30), each 64 bits wide.
Designed for high performance and energy efficiency.

Purpose of the Emulator

Simulate ARM64 instruction execution.

Initializing Emulator

Constructor initializes registers (x0-x30) to 0.
Memory and program counter (pc) initialized.
Instructions and labels are set up for later use.

Initializing Code

cpp

#include <iostream>
#include <unordered_map>
#include <vector>
#include <string>
#include <sstream>

class ARM64Emulator {
private:
    std::unordered_map<std::string, int> registers;
    std::unordered_map<int, int> memory;
    std::vector<std::string> instructions;
    std::unordered_map<std::string, int> labels;
    int pc;

public:
    ARM64Emulator() : pc(0) {
        for (int i = 0; i < 31; i++) {
            registers["x" + std::to_string(i)] = 0;
        }
    }

}

python

class ARM64Simulator:
    def __init__(self):
        self.registers = {f'x{i}': 0 for i in range(31)}
        self.memory = {}
        self.pc = 0
        self.instructions = []
        self.labels = {}

javascript

class ARM64Emulator {
    constructor() {
        this.registers = {};
        for (let i = 0; i < 31; i++) {
            this.registers[`x${i}`] = 0;
        }
        this.memory = {};
        this.pc = 0;
        this.instructions = [];
        this.labels = {};
    }

}

Loading the Program

loadProgram(program): Loads the program into the emulator.
Splits the program into instructions and filters out empty lines.
Calls parseLabels() to identify labels in the program.

Loading Code

cpp

    void loadProgram(const std::string& program) {
        std::istringstream stream(program);
        std::string line;
        while (std::getline(stream, line)) {
            std::string trimmed = trim(line);
            if (!trimmed.empty()) {
                instructions.push_back(trimmed);
            }
        }
        parseLabels();
    }

    void parseLabels() {
        for (size_t i = 0; i < instructions.size(); i++) {
            const std::string& line = instructions[i];
            size_t colonPos = line.find(':');
            if (colonPos != std::string::npos) {
                std::string label = trim(line.substr(0, colonPos));
                labels[label] = i;
            }
        }
    }

    std::string trim(const std::string& str) {
        size_t first = str.find_first_not_of(" \t");
        size_t last = str.find_last_not_of(" \t");
        return (first == std::string::npos || last == std::string::npos) ? "" : str.substr(first, (last - first + 1));
    }

python

    def load_program(self, program):
        self.instructions = [line.strip() for line in program.split('\n') if line.strip()]
        self.parse_labels()

    def parse_labels(self):
        for i, line in enumerate(self.instructions):
            if ':' in line:
                label = line.split(':')[0].strip()
                self.labels[label] = i

javascript

    loadProgram(program) {
        this.instructions = program.split('\n').map(line => line.trim()).filter(line => line);
        this.parseLabels();
    }

    parseLabels() {
        this.instructions.forEach((line, i) => {
            if (line.includes(':')) {
                const label = line.split(':')[0].trim();
                this.labels[label] = i;
            }
        });
    }

Running the Program

run(): Executes the loaded instructions one by one.
Skips label lines and calls executeInstruction(line) for each instruction.

Running Code

cpp

    void run() {
        while (pc < instructions.size()) {
            const std::string& line = instructions[pc];
            if (line.back() != ':') {
                executeInstruction(line);
            }
            pc++;
        }
    }

python

    def run(self):
        while self.pc < len(self.instructions):
            line = self.instructions[self.pc]
            if not line.endswith(':'):
                self.execute_instruction(line)
            self.pc += 1

javascript

    run() {
        while (this.pc < this.instructions.length) {
            const line = this.instructions[this.pc];
            if (!line.endsWith(':')) {
                this.executeInstruction(line);
            }
            this.pc++;
        }
    }

Executing Instructions

executeInstruction(line): Parses and executes a single instruction.
Supports ldr, str, add, mul, mov, svc, and b instructions.

Executing Code

cpp

    void executeInstruction(const std::string& line) {
        std::istringstream iss(line);
        std::vector<std::string> parts;
        std::string part;
        while (iss >> part) {
            parts.push_back(part);
        }

        const std::string& cmd = parts[0];
        // Handle 'ldr', 'str', 'add', 'mul', 'mov', 'svc', 'b'

    }

python

    def execute_instruction(self, line):
        parts = line.split()
        cmd = parts[0]

        # Handle 'ldr', 'str', 'add', 'mul', 'mov', 'svc', 'b'

javascript

    executeInstruction(line) {
        const parts = line.split(/\s+/);
        const cmd = parts[0];

        switch (cmd) {
            // Handle 'ldr', 'str', 'add', 'mul', 'mov', 'svc', 'b'
        }
    }

LDR and STR Instructions

ldr: Loads a value into a register.
str: Stores a value from a register into memory.

LDR Code

cpp

        if (cmd == "ldr") {
            std::string reg = parts[1].substr(0, parts[1].length() - 1); // remove trailing comma
            std::string value = parts[2];
            if (value[0] == '=') {
                int addr = std::stoi(value.substr(1));
                registers[reg] = addr;
            } else {
                int addr = registers[value.substr(1, value.length() - 2)];
                registers[reg] = memory[addr];
            }
        }

python

        if cmd == 'ldr':
            reg, value = parts[1].strip(','), parts[2]
            if value.startswith('='):
                addr = value[1:]
                self.registers[reg] = addr
            else:
                addr = self.registers[value.strip('[]')]
                self.registers[reg] = self.memory.get(addr, 0)

javascript

            case 'ldr': {
                const reg = parts[1].replace(',', '');
                const value = parts[2];
                if (value.startsWith('=')) {
                    const addr = value.substring(1);
                    this.registers[reg] = addr;
                } else {
                    const addr = this.registers[value.replace('[', '').replace(']', '')];
                    this.registers[reg] = this.memory[addr] || 0;
                }
                break;
            }

STR Code

cpp

          else if (cmd == "str") {
            std::string value = parts[1].substr(0, parts[1].length() - 1);
            std::string reg = parts[2].substr(1, parts[2].length() - 2);
            int addr = registers[reg];
            memory[addr] = registers[value];
        }

python

        elif cmd == 'str':
            value, reg = parts[1].strip(','), parts[2]
            addr = self.registers[reg.strip('[]')]
            self.memory[addr] = self.registers[value]

javascript

            case 'str': {
                const value = parts[1].replace(',', '');
                const reg = parts[2];
                const addr = this.registers[reg.replace('[', '').replace(']', '')];
                this.memory[addr] = this.registers[value];
                break;
            }

ADD and MUL Instructions

add: Adds values from two registers and stores the result in a destination register.
mul: Multiplies values from two registers and stores the result in a destination register.

ADD and MUL Code

cpp

          else if (cmd == "add") {
            std::string dest = parts[1].substr(0, parts[1].length() - 1);
            std::string src1 = parts[2].substr(0, parts[2].length() - 1);
            std::string src2 = parts[3];
            registers[dest] = registers[src1] + registers[src2];
        } else if (cmd == "mul") {
            std::string dest = parts[1].substr(0, parts[1].length() - 1);
            std::string src1 = parts[2].substr(0, parts[2].length() - 1);
            std::string src2 = parts[3];
            registers[dest] = registers[src1] * registers[src2];
        }

python

        elif cmd == 'add':
            dest, src1, src2 = parts[1].strip(','), parts[2].strip(','), parts[3]
            self.registers[dest] = self.registers[src1] + self.registers[src2]
        elif cmd == 'mul':
            dest, src1, src2 = parts[1].strip(','), parts[2].strip(','), parts[3]
            self.registers[dest] = self.registers[src1] * self.registers[src2]

javascript

            case 'add': {
                const dest = parts[1].replace(',', '');
                const src1 = parts[2].replace(',', '');
                const src2 = parts[3];
                this.registers[dest] = this.registers[src1] + this.registers[src2];
                break;
            }
            case 'mul': {
                const dest = parts[1].replace(',', '');
                const src1 = parts[2].replace(',', '');
                const src2 = parts[3];
                this.registers[dest] = this.registers[src1] * this.registers[src2];
                break;
            }

MOV and B Instructions

mov: Moves an immediate value into a register.
b: Branches to a labeled instruction.

MOV and B Code

cpp

          else if (cmd == "mov") {
            std::string reg = parts[1].substr(0, parts[1].length() - 1);
            int value = std::stoi(parts[2].substr(1));
            registers[reg] = value;
        } else if (cmd == "b") {
            std::string label = parts[1];
            pc = labels[label] - 1;
        } else {
            std::cout << "Unknown instruction: " << cmd << std::endl;
        }

python

        elif cmd == 'mov':
            reg, value = parts[1].strip(','), int(parts[2].strip('#'))
            self.registers[reg] = value
        elif cmd == 'svc':
            pass  # We will handle syscall separately
        elif cmd == 'b':
            label = parts[1]
            self.pc = self.labels[label] - 1
        else:
            print(f"Unknown instruction: {cmd}")

javascript

            case 'mov': {
                const reg = parts[1].replace(',', '');
                const value = parseInt(parts[2].replace('#', ''));
                this.registers[reg] = value;
                break;
            }
            case 'svc': {
                // Handle syscall separately
                break;
            }
            case 'b': {
                const label = parts[1];
                this.pc = this.labels[label] - 1;
                break;
            }
            default: {
                console.log(`Unknown instruction: ${cmd}`);
                break;
            }

Memory and Register Handling

initializeMemory(memoryInit): Initializes memory with given values.
printMemory(): Prints the current state of memory.
printRegisters(): Prints the current state of registers.

Memory and Register Code

cpp

    void printMemory() {
        std::cout << "Memory:" << std::endl;
        for (const auto& [k, v] : memory) {
            std::cout << k << ": " << v << std::endl;
        }
    }

    void printRegisters() {
        std::cout << "Registers:" << std::endl;
        for (const auto& [k, v] : registers) {
            std::cout << k << ": " << v << std::endl;
        }
    }

    void initializeMemory(const std::unordered_map<std::string, int>& memoryInit) {
        for (const auto& [key, value] : memoryInit) {
            memory[std::stoi(key)] = value;
        }
    }

python

    def print_memory(self):
        print("Memory:")
        for k, v in self.memory.items():
            print(f"{k}: {v}")

    def print_registers(self):
        print("Registers:")
        for k, v in self.registers.items():
            print(f"{k}: {v}")

    def initialize_memory(self, memory_init):
        for var, value in memory_init.items():
            self.memory[var] = value

javascript

    printMemory() {
        console.log("Memory:");
        for (const [k, v] of Object.entries(this.memory)) {
            console.log(`${k}: ${v}`);
        }
    }

    printRegisters() {
        console.log("Registers:");
        for (const [k, v] of Object.entries(this.registers)) {
            console.log(`${k}: ${v}`);
        }
    }

    initializeMemory(memoryInit) {
        this.memory = { ...memoryInit };
    }

Putting It All Together

Define the program to be executed.
Initialize memory with values.
Create emulator instance, load program, run, and print results.

Driver Code

cpp

int main() {
    std::string program = 
        "ldr x0, =5\n"
        "ldr x1, [x0]\n"
        "ldr x0, =7\n"
        "ldr x2, [x0]\n"
        "add x3, x1, x2\n"
        "ldr x0, =3\n"
        "ldr x4, [x0]\n"
        "mul x5, x3, x4\n"
        "ldr x0, =0\n"
        "str x5, [x0]\n";

    std::unordered_map<std::string, int> memoryInit = {
        {"5", 5},
        {"7", 7},
        {"3", 3},
        {"0", 0}
    };

    ARM64Emulator emulator;
    emulator.initializeMemory(memoryInit);
    emulator.loadProgram(program);
    emulator.run();
    emulator.printRegisters();
    emulator.printMemory();

    return 0;
}

python

program = """
ldr x0, =num1
ldr x1, [x0]
ldr x0, =num2
ldr x2, [x0]
add x3, x1, x2
ldr x0, =multiplier
ldr x4, [x0]
mul x5, x3, x4
ldr x0, =result
str x5, [x0]
"""

memory_init = {
    'num1': 5,
    'num2': 7,
    'multiplier': 3,
    'result': 0
}

simulator = ARM64Simulator()
simulator.initialize_memory(memory_init)
simulator.load_program(program)
simulator.run()
simulator.print_registers()
simulator.print_memory()

javascript

const program = `
ldr x0, =num1
ldr x1, [x0]
ldr x0, =num2
ldr x2, [x0]
add x3, x1, x2
ldr x0, =multiplier
ldr x4, [x0]
mul x5, x3, x4
ldr x0, =result
str x5, [x0]
`;

const memoryInit = {
    'num1': 5,
    'num2': 7,
    'multiplier': 3,
    'result': 0
};

const emulator = new ARM64Emulator();
emulator.initializeMemory(memoryInit);
emulator.loadProgram(program);
emulator.run();
emulator.printRegisters();
emulator.printMemory();

Future Work

The journey doesn't end here! Building a simple emulator is just the beginning. You can explore advanced instruction sets with following tasks:-

Implement additional ARM64 instructions to enhance your emulator’s capabilities.
Explore conditional instructions, floating-point operations, and vector processing.

GitHub

https://github.com/ToyMath/ToyARM64Emulator