Forem: aelassas

Servy vs. NSSM vs. WinSW

aelassas — Mon, 26 Jan 2026 18:51:56 +0000

If you have worked in the Windows ecosystem for a while, you know the situation: you have a high-performance Node.js, Python, or Go application that needs to run as a background service. Most developers turn to NSSM or WinSW to get the job done.

These tools have stood the test of time, but their age shows. They lack modern monitoring, robust process handling, and flexible automation.

In this post, we're looking at the old guard versus the new player on the block: Servy.

The Contenders

NSSM (Non-Sucking Service Manager): The "classic." It's incredibly lightweight but hasn't seen a stable update in over a decade. It lacks modern observability and often struggles with complex process trees.
WinSW (Windows Service Wrapper): A staple for Jenkins users. It's powerful and XML-driven, but it's currently in maintenance limbo and lacks a graphical interface for quick troubleshooting.
Servy: A modern, open-source alternative. It bridges the gap by offering a high-performance Manager GUI and a robust CLI/PowerShell module for CI/CD pipelines.

Why the Wrapper Matters

A service wrapper is not just a starter script. In production, it is the heartbeat of your application. If your wrapper cannot handle graceful signal propagation or proper process cleanup, you risk leaked resources and orphaned processes that manual reboots cannot always fix.

The Comparison: Feature Breakdown

Feature	Servy	NSSM	WinSW
GUI Management	✅ Real-time monitoring and config	⚪ Basic installer GUI only	❌ No GUI
CLI / Automation	✅ PowerShell, CLI and CI/CD support	✅ CLI	✅ CLI only
Pre/Post Launch Hooks	✅ Advanced with retries and timeouts	❌	⚪ Basic
Pre/Post Stop Hooks	✅ Advanced pulsed cleanup	❌	❌
Performance Tracking	✅ Real-time CPU and RAM graphs	❌	❌
Service Accounts	✅ System, Domain, AD, and gMSA support	⚪ Limited	⚪ Limited
Logging and Rotation	✅ Advanced size and date rotation	⚪ Basic	⚪ Basic
Live Console Preview	✅ Real-time stdout and stderr streaming	❌	❌
Dependencies Preview	✅ Advanced with statuses	❌	❌
Process Tree Safety	✅ Ctrl+C, Graceful Stop, Force Kill	⚪ Basic	⚪ Basic
Zombie Prevention	✅ Recursive tree cleanup	❌	❌
Health and Recovery	✅ Built-in monitoring and auto-restart	❌	⚪ Limited
Notifications	✅ Windows OS alerts and Email	❌	❌
Config Portability	✅ Export and Import (XML/JSON)	❌	❌
Actively Maintained	✅ Yes	❌ No (Inactive)	❌ No (Inactive)

The Servy Advantage

Servy was designed to address the limitations of legacy wrappers and provide a robust, reliable solution for modern services. Beyond basic service management, it supports scenarios that NSSM and WinSW cannot handle efficiently:

Observability and Diagnostics: Servy provides live CPU and RAM graphs. It can stream the standard output and error logs in real time. NSSM and WinSW require external monitoring tools to achieve this level of visibility.
Advanced Lifecycle Hooks: Pre-launch, post-launch, pre-stop, and post-stop hooks with retry logic, timeouts, and failure handling allow complex orchestration. Legacy wrappers either lack hooks or offer only minimal functionality.
Process Tree Management: Servy safely propagates stop signals and kills descendant processes recursively, preventing orphaned processes from consuming system resources. This ensures clean teardowns even in nested process trees.
Self-Healing and Notifications: Built-in health checks and automatic recovery, including service restart or process restart, help maintain uptime. Servy can trigger notifications via toast alerts or email when failures occur, which NSSM and WinSW do not natively provide.
Flexible Accounts and Security: Servy supports LocalSystem, domain accounts, Active Directory accounts, and gMSA, along with encrypted password storage. Legacy wrappers are limited in account support and security features.
Portable Configurations: Servy supports exporting and importing configurations in XML and JSON formats. This enables easy replication, migration, or backup of service setups.
Cross-Version Compatibility: Servy provides builds for modern and legacy Windows systems, allowing organizations with mixed environments to standardize on a single wrapper.

In short, Servy solves the pain points that legacy wrappers leave unresolved and empowers teams with visibility, reliability, and control.

Conclusion

While NSSM and WinSW served us well for years, they belong to a different era of DevOps. For professionals who need reliability, real-time monitoring, and deep integration with modern CI/CD, Servy is the clear successor. It's free, open-source, and ready for Windows 11 and Server 2025+. It also provides builds compatible with legacy systems, including Windows 7 and above, as well as Windows Server 2008 and above.

From Zero to Storefront: My Journey Building a Property Rental Platform

aelassas — Sun, 10 Nov 2024 10:57:04 +0000

Introduction
Tech Stack
Quick Overview
API
Frontend
Mobile App
Admin Dashboard
Points of Interest
Resources

Source code: https://github.com/aelassas/movinin

Demo: https://movinin.dynv6.net:3004

Introduction

The idea emerged from a desire to build without boundaries – a fully customizable and operational property rental platform where every aspect is within your control:

Own the UI/UX: Design unique customer experiences without fighting against template limitations
Control the Backend: Implement custom business logic and data structures that perfectly match the requirements
Master DevOps: Deploy, scale, and monitor the application with preferred tools and workflows
Extend Freely: Add new features and integrations without platform constraints or additional fees

Tech Stack

Here's the tech stack that made it possible:

TypeScript
Node.js
MongoDB
React
MUI
Expo
Stripe
Docker

A key design decision was made to use TypeScript due to its numerous advantages. TypeScript offers strong typing, tooling, and integration, resulting in high-quality, scalable, more readable and maintainable code that is easy to debug and test.

I chose React for its powerful rendering capabilities, MongoDB for flexible data modeling, and Stripe for secure payment processing.

By choosing this stack, you're not just building a website and mobile app – you're investing in a foundation that can evolve with your needs, backed by robust open-source technologies and a growing developer community.

Quick overview

In this section, you'll see the main pages of the frontend, the admin dashboard and the mobile app.

Frontend

From the frontend, the customer can search for available properties, choose a property and checkout.

Below is the main page of the frontend where the customer can a location point and time, and search for available properties.

Below is the search result of the main page where the customer can choose a property for rental.

Below is the page where the customer can view the details of the property:

Below is a view of the images of the property:

Below is the checkout page where the customer can set rental options and checkout. If the customer is not registered, he can checkout and register at the same time. He will receive a confirmation and activation email to set his password if he is not registered yet.

Below is the sign in page. On production, authentication cookies are httpOnly, signed, secure and strict sameSite. These options prevent XSS, CSRF and MITM attacks. Authentication cookies are protected against XST attacks as well via a custom middleware.

Below is the sign up page.

Below is the page where the customer can see and manage his bookings.

Below is the page where the customer can see a booking in detail.

Below is the page where the customer can see his notifications.

Below is the page where the customer can manage his settings.

Below is the page where the customer can change his password.

That's it. That's the main pages of the frontend.

Admin Dashboard

Three types of users:

Admins: They have full access to the admin dashboard. They can do everything.
Agencies: They have limited access on the admin dashboard. They can only manage their properties, bookings and customers.
Customers: They have access to the frontend and the mobile app only. They cannot access the admin dashboard.

The platform is designed to work with multiple agencies. Each agency can manage its properties, customers and bookings from the admin dashboard. The platform can also work with only one agency as well.

From the backend, admins can create and manage agencies, properties, locations, customers and bookings.

When new agencies are created, they receive an email prompting them to create their account to access the admin dashboard so they can manage their properties, customers and bookings.

Below is the sign in page of the admin dashboard.

Below is the dashboard page where admins and agencies can see and manage bookings.

If the status of a booking changes, the related customer will receive a notification and an email.

Below is the page where properties are displayed and can be managed.

Below is the page where admins and agencies can create new properties by providing images and property info. For cancellation for free, set it to 0. Otherwise, set the price of the option or leave it empty if you don't want to include it.

Below is the page where admins and agencies can edit properties.

Below is the page where admins can manage customers.

Below is the page where to create bookings if the agency wants to create a booking from the admin dashboard. Otherwise, bookings are created automatically when the checkout process is completed from the frontend or the mobile app.

Below is the page where to edit bookings.

Below is the page where to manage agencies.

Below is the page where to create new agencies.

Below is the page where to edit agencies.

Below is the page where to see agencies' properties.

Below is the page where to see customer's bookings.

Below is the page where admins and agencies can manage their settings.

There are other pages but these are the main pages of the admin dashboard.

That's it. That's the main pages of the admin dashboard.

API

The API exposes all functions needed for the admin dashboard, the frontend and the mobile app. The API follows the MVC design pattern. JWT is used for authentication. There are some functions that need authentication such as functions related to managing properties, bookings and customers, and others that do not need authentication such as retrieving locations and available properties for non authenticated users:

./api/src/models/ folder contains MongoDB models.
./api/src/routes/ folder contains Express routes.
./api/src/controllers/ folder contains controllers.
./api/src/middlewares/ folder contains middlewares.
./api/src/config/env.config.ts contains the configuration and TypeScript type definitions.
./api/src/lang/ folder contains localization.
./api/src/app.ts is the main server where routes are loaded.
./api/index.ts is the main entry point of the API.

index.ts is the main entry point of the API:

import 'dotenv/config'
import process from 'node:process'
import fs from 'node:fs/promises'
import http from 'node:http'
import https, { ServerOptions } from 'node:https'
import app from './app'
import * as databaseHelper from './common/databaseHelper'
import * as env from './config/env.config'
import * as logger from './common/logger'

if (
  await databaseHelper.connect(env.DB_URI, env.DB_SSL, env.DB_DEBUG) 
  && await databaseHelper.initialize()
) {
  let server: http.Server | https.Server

  if (env.HTTPS) {
    https.globalAgent.maxSockets = Number.POSITIVE_INFINITY
    const privateKey = await fs.readFile(env.PRIVATE_KEY, 'utf8')
    const certificate = await fs.readFile(env.CERTIFICATE, 'utf8')
    const credentials: ServerOptions = { key: privateKey, cert: certificate }
    server = https.createServer(credentials, app)

    server.listen(env.PORT, () => {
      logger.info('HTTPS server is running on Port', env.PORT)
    })
  } else {
    server = app.listen(env.PORT, () => {
      logger.info('HTTP server is running on Port', env.PORT)
    })
  }

  const close = () => {
    logger.info('Gracefully stopping...')
    server.close(async () => {
      logger.info(`HTTP${env.HTTPS ? 'S' : ''} server closed`)
      await databaseHelper.close(true)
      logger.info('MongoDB connection closed')
      process.exit(0)
    })
  }

  ['SIGINT', 'SIGTERM', 'SIGQUIT'].forEach((signal) => process.on(signal, close))
}

This is a TypeScript file that starts a server using Node.js and Express. It imports several modules including dotenv, process, fs, http, https, mongoose, and app. It then checks if the HTTPS environment variable is set to true, and if so, creates an HTTPS server using the https module and the provided private key and certificate. Otherwise, it creates an HTTP server using the http module. The server listens on the port specified in the PORT environment variable.

The close function is defined to gracefully stop the server when a termination signal is received. It closes the server and the MongoDB connection, and then exits the process with a status code of 0. Finally, it registers the close function to be called when the process receives a SIGINT, SIGTERM, or SIGQUIT signal.

app.ts is the main entry point of the api:

import express from 'express'
import compression from 'compression'
import helmet from 'helmet'
import nocache from 'nocache'
import cookieParser from 'cookie-parser'
import i18n from './lang/i18n'
import * as env from './config/env.config'
import cors from './middlewares/cors'
import allowedMethods from './middlewares/allowedMethods'
import agencyRoutes from './routes/agencyRoutes'
import bookingRoutes from './routes/bookingRoutes'
import locationRoutes from './routes/locationRoutes'
import notificationRoutes from './routes/notificationRoutes'
import propertyRoutes from './routes/propertyRoutes'
import userRoutes from './routes/userRoutes'
import stripeRoutes from './routes/stripeRoutes'
import countryRoutes from './routes/countryRoutes'
import * as helper from './common/helper'

const app = express()

app.use(helmet.contentSecurityPolicy())
app.use(helmet.dnsPrefetchControl())
app.use(helmet.crossOriginEmbedderPolicy())
app.use(helmet.frameguard())
app.use(helmet.hidePoweredBy())
app.use(helmet.hsts())
app.use(helmet.ieNoOpen())
app.use(helmet.noSniff())
app.use(helmet.permittedCrossDomainPolicies())
app.use(helmet.referrerPolicy())
app.use(helmet.xssFilter())
app.use(helmet.originAgentCluster())
app.use(helmet.crossOriginResourcePolicy({ policy: 'cross-origin' }))
app.use(helmet.crossOriginOpenerPolicy())

app.use(nocache())
app.use(compression({ threshold: 0 }))
app.use(express.urlencoded({ limit: '50mb', extended: true }))
app.use(express.json({ limit: '50mb' }))

app.use(cors())
app.options('*', cors())
app.use(cookieParser(env.COOKIE_SECRET))
app.use(allowedMethods)

app.use('/', agencyRoutes)
app.use('/', bookingRoutes)
app.use('/', locationRoutes)
app.use('/', notificationRoutes)
app.use('/', propertyRoutes)
app.use('/', userRoutes)
app.use('/', stripeRoutes)
app.use('/', countryRoutes)

i18n.locale = env.DEFAULT_LANGUAGE

helper.mkdir(env.CDN_USERS)
helper.mkdir(env.CDN_TEMP_USERS)
helper.mkdir(env.CDN_PROPERTIES)
helper.mkdir(env.CDN_TEMP_PROPERTIES)
helper.mkdir(env.CDN_LOCATIONS)
helper.mkdir(env.CDN_TEMP_LOCATIONS)

export default app

First of all, we retrieve MongoDB connection string, then we establish a connection with MongoDB database. Then we create an Express app and load middlewares such as cors, compression, helmet, and nocache. We set up various security measures using the helmet middleware library. we also import various route files for different parts of the application such as supplierRoutes, bookingRoutes, locationRoutes, notificationRoutes, propertyRoutes, and userRoutes. Finally, we load Express routes and export app.

There are 8 routes in the API. Each route has its own controller following the MVC design pattern and SOLID principles. Below are the main routes:

userRoutes: Provides REST functions related to users
agencyRoutes: Provides REST functions related to agencies
countryRoutes: Provides REST functions related to countries
locationRoutes: Provides REST functions related to locations
propertyRoutes: Provides REST functions related to properties
bookingRoutes: Provides REST functions related to bookings
notificationRoutes: Provides REST functions related to notifications
stripeRoutes: Provides REST functions related to Stripe payment gateway

We are not going to explain each route one by one. We'll take, for example, propertyRoutes and see how it was made. You can browse the source code and see all the routes.

Here is propertyRoutes.ts:

import express from 'express'
import multer from 'multer'
import routeNames from '../config/propertyRoutes.config'
import authJwt from '../middlewares/authJwt'
import * as propertyController from '../controllers/propertyController'

const routes = express.Router()

routes.route(routeNames.create).post(authJwt.verifyToken, propertyController.create)
routes.route(routeNames.update).put(authJwt.verifyToken, propertyController.update)
routes.route(routeNames.checkProperty).get(authJwt.verifyToken, propertyController.checkProperty)
routes.route(routeNames.delete).delete(authJwt.verifyToken, propertyController.deleteProperty)
routes.route(routeNames.uploadImage).post([authJwt.verifyToken, multer({ storage: multer.memoryStorage() }).single('image')], propertyController.uploadImage)
routes.route(routeNames.deleteImage).post(authJwt.verifyToken, propertyController.deleteImage)
routes.route(routeNames.deleteTempImage).post(authJwt.verifyToken, propertyController.deleteTempImage)
routes.route(routeNames.getProperty).get(propertyController.getProperty)
routes.route(routeNames.getProperties).post(authJwt.verifyToken, propertyController.getProperties)
routes.route(routeNames.getBookingProperties).post(authJwt.verifyToken, propertyController.getBookingProperties)
routes.route(routeNames.getFrontendProperties).post(propertyController.getFrontendProperties)

export default routes

First of all, we create an Express Router. Then, we create the routes using their name, method, middlewares and controllers.

routeNames contains propertyRoutes route names:

const routes = {
  create: '/api/create-property',
  update: '/api/update-property',
  delete: '/api/delete-property/:id',
  uploadImage: '/api/upload-property-image',
  deleteTempImage: '/api/delete-temp-property-image/:fileName',
  deleteImage: '/api/delete-property-image/:property/:image',
  getProperty: '/api/property/:id/:language',
  getProperties: '/api/properties/:page/:size',
  getBookingProperties: '/api/booking-properties/:page/:size',
  getFrontendProperties: '/api/frontend-properties/:page/:size',
  checkProperty: '/api/check-property/:id',
}

export default routes

propertyController contains the main business logic regarding locations. We are not going to see all the source code of the controller since it's quite large but we'll take create controller function for example.

Below is Property model:

import { Schema, model } from 'mongoose'
import * as movininTypes from ':movinin-types'
import * as env from '../config/env.config'

const propertySchema = new Schema<env.Property>(
  {
    name: {
      type: String,
      required: [true, "can't be blank"],
    },
    type: {
      type: String,
      enum: [
        movininTypes.PropertyType.House,
        movininTypes.PropertyType.Apartment,
        movininTypes.PropertyType.Townhouse,
        movininTypes.PropertyType.Plot,
        movininTypes.PropertyType.Farm,
        movininTypes.PropertyType.Commercial,
        movininTypes.PropertyType.Industrial,
      ],
      required: [true, "can't be blank"],
    },
    agency: {
      type: Schema.Types.ObjectId,
      required: [true, "can't be blank"],
      ref: 'User',
      index: true,
    },
    description: {
      type: String,
      required: [true, "can't be blank"],
    },
    available: {
      type: Boolean,
      default: true,
    },
    image: {
      type: String,
    },
    images: {
      type: [String],
    },
    bedrooms: {
      type: Number,
      required: [true, "can't be blank"],
      validate: {
        validator: Number.isInteger,
        message: '{VALUE} is not an integer value',
      },
    },
    bathrooms: {
      type: Number,
      required: [true, "can't be blank"],
      validate: {
        validator: Number.isInteger,
        message: '{VALUE} is not an integer value',
      },
    },
    kitchens: {
      type: Number,
      default: 1,
      validate: {
        validator: Number.isInteger,
        message: '{VALUE} is not an integer value',
      },
    },
    parkingSpaces: {
      type: Number,
      default: 0,
      validate: {
        validator: Number.isInteger,
        message: '{VALUE} is not an integer value',
      },
    },
    size: {
      type: Number,
    },
    petsAllowed: {
      type: Boolean,
      required: [true, "can't be blank"],
    },
    furnished: {
      type: Boolean,
      required: [true, "can't be blank"],
    },
    minimumAge: {
      type: Number,
      required: [true, "can't be blank"],
      min: env.MINIMUM_AGE,
      max: 99,
    },
    location: {
      type: Schema.Types.ObjectId,
      ref: 'Location',
      required: [true, "can't be blank"],
    },
    address: {
      type: String,
    },
    price: {
      type: Number,
      required: [true, "can't be blank"],
    },
    hidden: {
      type: Boolean,
      default: false,
    },
    cancellation: {
      type: Number,
      default: 0,
    },
    aircon: {
      type: Boolean,
      default: false,
    },
    rentalTerm: {
      type: String,
      enum: [
        movininTypes.RentalTerm.Monthly,
        movininTypes.RentalTerm.Weekly,
        movininTypes.RentalTerm.Daily,
        movininTypes.RentalTerm.Yearly,
      ],
      required: [true, "can't be blank"],
    },
  },
  {
    timestamps: true,
    strict: true,
    collection: 'Property',
  },
)

const Property = model<env.Property>('Property', propertySchema)

export default Property

Below is Property type:

export interface Property extends Document {
  name: string
  type: movininTypes.PropertyType
  agency: Types.ObjectId
  description: string
  image: string
  images?: string[]
  bedrooms: number
  bathrooms: number
  kitchens?: number
  parkingSpaces?: number,
  size?: number
  petsAllowed: boolean
  furnished: boolean
  minimumAge: number
  location: Types.ObjectId
  address?: string
  price: number
  hidden?: boolean
  cancellation?: number
  aircon?: boolean
  available?: boolean
  rentalTerm: movininTypes.RentalTerm
}

A property is composed of:

A name
A type (Apartment, Commercial, Farm, House, Industrial, Plot, Townhouse)
A reference to the agency who created it
A description
A main image
Additional images
Number of bedrooms
Number of bathrooms
Number of kitchens
Number of parking spaces
A Size
Minimum age for rental
A location
An address (optional)
A price
A rental term (Monthly, Weekly, Daily, Yearly)
Cancellation price (set it to 0 to be included for free, leave it empty if you don't want to include it, or set the price for cancellation)
A flag that indicates whether pets are allowed or not
A flag that indicates whether the property is furnished or not
A flag that indicates whether the property is hidden or not
A flag that indicates whether aircon is available or not
A flag that indicates whether the property is available for rental or not

Below is create controller function:

export const create = async (req: Request, res: Response) => {
  const { body }: { body: movininTypes.CreatePropertyPayload } = req

  try {
    const {
      name,
      type,
      agency,
      description,
      image: imageFile,
      images,
      bedrooms,
      bathrooms,
      kitchens,
      parkingSpaces,
      size,
      petsAllowed,
      furnished,
      minimumAge,
      location,
      address,
      price,
      hidden,
      cancellation,
      aircon,
      rentalTerm,
    } = body

    const _property = {
      name,
      type,
      agency,
      description,
      bedrooms,
      bathrooms,
      kitchens,
      parkingSpaces,
      size,
      petsAllowed,
      furnished,
      minimumAge,
      location,
      address,
      price,
      hidden,
      cancellation,
      aircon,
      rentalTerm,
    }

    const property = new Property(_property)
    await property.save()

    // image
    const _image = path.join(env.CDN_TEMP_PROPERTIES, imageFile)
    if (await helper.exists(_image)) {
      const filename = `${property._id}_${Date.now()}${path.extname(imageFile)}`
      const newPath = path.join(env.CDN_PROPERTIES, filename)

      await fs.rename(_image, newPath)
      property.image = filename
    } else {
      await Property.deleteOne({ _id: property._id })
      const err = 'Image file not found'
      logger.error(i18n.t('ERROR'), err)
      return res.status(400).send(i18n.t('ERROR') + err)
    }

    // images
    property.images = []
    if (images) {
      let i = 1
      for (const img of images) {
        const _img = path.join(env.CDN_TEMP_PROPERTIES, img)

        if (await helper.exists(_img)) {
          const filename = `${property._id}_${uuid()}_${Date.now()}_${i}${path.extname(img)}`
          const newPath = path.join(env.CDN_PROPERTIES, filename)

          await fs.rename(_img, newPath)
          property.images.push(filename)
        } else {
          await Property.deleteOne({ _id: property._id })
          const err = 'Image file not found'
          logger.error(i18n.t('ERROR'), err)
          return res.status(400).send(i18n.t('ERROR') + err)
        }
        i += 1
      }
    }

    await property.save()

    return res.json(property)
  } catch (err) {
    logger.error(`[property.create] ${i18n.t('DB_ERROR')} ${JSON.stringify(body)}`, err)
    return res.status(400).send(i18n.t('ERROR') + err)
  }
}

Frontend

The frontend is a web application built with Node.js, React, MUI and TypeScript. From the frontend, the customer can search for available cars depending on pickup and drop-off points and time, choose a car and proceed to checkout:

./frontend/src/assets/ folder contains CSS and images.
./frontend/src/pages/ folder contains React pages.
./frontend/src/components/ folder contains React components.
./frontend/src/services/ contains api client services.
./frontend/src/App.tsx is the main React App that contains routes.
./frontend/src/index.tsx is the main entry point of the frontend.

TypeScript type definitions are defined in the package ./packages/movinin-types.

App.tsx is the main react App:

import React, { lazy, Suspense } from 'react'
import { BrowserRouter as Router, Route, Routes } from 'react-router-dom'
import env from '@/config/env.config'
import { GlobalProvider } from '@/context/GlobalContext'
import { init as initGA } from '@/common/ga4'

if (env.GOOGLE_ANALYTICS_ENABLED) {
  initGA()
}

const SignIn = lazy(() => import('@/pages/SignIn'))
const SignUp = lazy(() => import('@/pages/SignUp'))
const Activate = lazy(() => import('@/pages/Activate'))
const ForgotPassword = lazy(() => import('@/pages/ForgotPassword'))
const ResetPassword = lazy(() => import('@/pages/ResetPassword'))
const Home = lazy(() => import('@/pages/Home'))
const Search = lazy(() => import('@/pages/Search'))
const Property = lazy(() => import('@/pages/Property'))
const Checkout = lazy(() => import('@/pages/Checkout'))
const CheckoutSession = lazy(() => import('@/pages/CheckoutSession'))
const Bookings = lazy(() => import('@/pages/Bookings'))
const Booking = lazy(() => import('@/pages/Booking'))
const Settings = lazy(() => import('@/pages/Settings'))
const Notifications = lazy(() => import('@/pages/Notifications'))
const ToS = lazy(() => import('@/pages/ToS'))
const About = lazy(() => import('@/pages/About'))
const ChangePassword = lazy(() => import('@/pages/ChangePassword'))
const Contact = lazy(() => import('@/pages/Contact'))
const NoMatch = lazy(() => import('@/pages/NoMatch'))
const Agencies = lazy(() => import('@/pages/Agencies'))
const Locations = lazy(() => import('@/pages/Locations'))

const App = () => (
  <GlobalProvider>
    <Router>
      <div className="app">
        <Suspense fallback={<></>}>
          <Routes>
            <Route path="/sign-in" element={<SignIn />} />
            <Route path="/sign-up" element={<SignUp />} />
            <Route path="/activate" element={<Activate />} />
            <Route path="/forgot-password" element={<ForgotPassword />} />
            <Route path="/reset-password" element={<ResetPassword />} />
            <Route path="/" element={<Home />} />
            <Route path="/search" element={<Search />} />
            <Route path="/property" element={<Property />} />
            <Route path="/checkout" element={<Checkout />} />
            <Route path="/checkout-session/:sessionId" element={<CheckoutSession />} />
            <Route path="/bookings" element={<Bookings />} />
            <Route path="/booking" element={<Booking />} />
            <Route path="/settings" element={<Settings />} />
            <Route path="/notifications" element={<Notifications />} />
            <Route path="/change-password" element={<ChangePassword />} />
            <Route path="/about" element={<About />} />
            <Route path="/tos" element={<ToS />} />
            <Route path="/contact" element={<Contact />} />
            <Route path="/agencies" element={<Agencies />} />
            <Route path="/destinations" element={<Locations />} />

            <Route path="*" element={<NoMatch />} />
          </Routes>
        </Suspense>
      </div>
    </Router>
  </GlobalProvider>
)

export default App

We are using React lazy loading to load each route.

We are not going to cover each page of the frontend, but you can browse the source code and see each one.

Mobile App

The platform provides a native mobile app for Android and iOS. The mobile app is built with React Native, Expo and TypeScript. Like for the frontend, the mobile app allows the customer to search for available cars depending on pickup and drop-off points and time, choose a car and proceed to checkout.

The customer receives push notifications if his booking is updated from the backend. Push notifications are built with Node.js, Expo Server SDK and Firebase.

./mobile/assets/ folder contains images.
./mobile/screens/ folder contains main React Native screens.
./mobile/components/ folder contains React Native components.
./mobile/services/ contains api client services.
./mobile/App.tsx is the main React Native App.

TypeScript type definitions are defined in:

./mobile/types/index.d.ts
./mobile/types/env.d.ts
./mobile/miscellaneous/movininTypes.ts

./mobile/types/ is loaded in ./mobile/tsconfig.json as follow:

{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "strict": true,
    "typeRoots": [
      "./types"
    ]
  }
}

App.tsx is the main entry point of the React Native app:

import 'react-native-gesture-handler'
import React, { useCallback, useEffect, useRef, useState } from 'react'
import { RootSiblingParent } from 'react-native-root-siblings'
import { NavigationContainer, NavigationContainerRef } from '@react-navigation/native'
import { StatusBar as ExpoStatusBar } from 'expo-status-bar'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { Provider } from 'react-native-paper'
import * as SplashScreen from 'expo-splash-screen'
import * as Notifications from 'expo-notifications'
import { StripeProvider } from '@stripe/stripe-react-native'
import DrawerNavigator from './components/DrawerNavigator'
import * as helper from './common/helper'
import * as NotificationService from './services/NotificationService'
import * as UserService from './services/UserService'
import { GlobalProvider } from './context/GlobalContext'
import * as env from './config/env.config'

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: true,
    shouldSetBadge: true,
  }),
})

//
// Prevent native splash screen from autohiding before App component declaration
//
SplashScreen.preventAutoHideAsync()
  .then((result) => console.log(`SplashScreen.preventAutoHideAsync() succeeded: ${result}`))
  .catch(console.warn) // it's good to explicitly catch and inspect any error

const App = () => {
  const [appIsReady, setAppIsReady] = useState(false)

  const responseListener = useRef<Notifications.Subscription>()
  const navigationRef = useRef<NavigationContainerRef<StackParams>>(null)

  useEffect(() => {
    const register = async () => {
      const loggedIn = await UserService.loggedIn()
      if (loggedIn) {
        const currentUser = await UserService.getCurrentUser()
        if (currentUser?._id) {
          await helper.registerPushToken(currentUser._id)
        } else {
          helper.error()
        }
      }
    }

    //
    // Register push notifiations token
    //
    register()

    //
    // This listener is fired whenever a user taps on or interacts with a notification (works when app is foregrounded, backgrounded, or killed)
    //
    responseListener.current = Notifications.addNotificationResponseReceivedListener(async (response) => {
      try {
        if (navigationRef.current) {
          const { data } = response.notification.request.content

          if (data.booking) {
            if (data.user && data.notification) {
              await NotificationService.markAsRead(data.user, [data.notification])
            }
            navigationRef.current.navigate('Booking', { id: data.booking })
          } else {
            navigationRef.current.navigate('Notifications', {})
          }
        }
      } catch (err) {
        helper.error(err, false)
      }
    })

    return () => {
      Notifications.removeNotificationSubscription(responseListener.current!)
    }
  }, [])

  setTimeout(() => {
    setAppIsReady(true)
  }, 500)

  const onReady = useCallback(async () => {
    if (appIsReady) {
      //
      // This tells the splash screen to hide immediately! If we call this after
      // `setAppIsReady`, then we may see a blank screen while the app is
      // loading its initial state and rendering its first pixels. So instead,
      // we hide the splash screen once we know the root view has already
      // performed layout.
      //
      await SplashScreen.hideAsync()
    }
  }, [appIsReady])

  if (!appIsReady) {
    return null
  }

  return (
    <GlobalProvider>
      <SafeAreaProvider>
        <Provider>
          <StripeProvider publishableKey={env.STRIPE_PUBLISHABLE_KEY} merchantIdentifier={env.STRIPE_MERCHANT_IDENTIFIER}>
            <RootSiblingParent>
              <NavigationContainer ref={navigationRef} onReady={onReady}>
                <ExpoStatusBar style="light" backgroundColor="rgba(0, 0, 0, .9)" />
                <DrawerNavigator />
              </NavigationContainer>
            </RootSiblingParent>
          </StripeProvider>
        </Provider>
      </SafeAreaProvider>
    </GlobalProvider>
  )
}

export default App

We are not going to cover each screen of the mobile app, but you can browse the source code and see each one.

Admin Dashboard

The admin dashboard is a web application built with Node.js, React, MUI and TypeScript. From the backend, admins can create and manage suppliers, cars, locations, customers and bookings. When new suppliers are created from the backend, they will receive an email prompting them to create an account in order to access the admin dashboard and manage their car fleet and bookings.

./backend/assets/ folder contains CSS and images.
./backend/pages/ folder contains React pages.
./backend/components/ folder contains React components.
./backend/services/ contains api client services.
./backend/App.tsx is the main React App that contains routes.
./backend/index.tsx is the main entry point of the admin dashboard.

TypeScript type definitions are defined in the package ./packages/movinin-types.

App.tsx of the admin dashboard follow similar logic like App.tsx of the frontend.

We are not going to cover each page of the admin dashboard but you can browse the source code and see each one.

Points of Interest

Building the mobile app with React Native and Expo is very easy. Expo makes mobile development with React Native very simple.

Using the same language (TypeScript) for backend, frontend and mobile development is very convenient.

TypeScript is a very interesting language and has many advantages. By adding static typing to JavaScript, we can avoid many bugs and produce high quality, scalable, more readable and maintainable code that is easy to debug and test.

That's it! I hope you enjoyed reading this article.

Resources

Functional Programming in C#

aelassas — Fri, 08 Nov 2024 08:35:37 +0000

Introduction
Development Environment
Representing Data Through Functions
1. Sets
2. Binary Operations
3. Go Further
Euclidean Plane
1. Drawing a Disk
2. Drawing Horizontal and Vertical Half-planes
3. Functions
4. Go Further
Fractals
1. Complex Numbers and Drawing
2. Mandelbrot Fractal
3. Newton Fractal
4. Go Further
Introduction to Laziness
Unit Tests

You can find source code here: https://github.com/aelassas/functional-cs

Introduction

Functional programming is a programming paradigm based on functions, their compositions, and also on decomposition into functions.

There are two possible properties of functions:

Purity: Functions have results that depend strictly on their arguments, with no other side effect. Purity leads to compartmentalization, localization, stability, and determinism.
First-class citizenship: Functions have value status. Functions can be named, assigned, typed, created on demand, passed as an argument to a function, be the result of a function, and stored in a data structure. First-class citizenship leads to flexibility of use and compositionality.

Functional programming consists in exploiting one and/or the other of these two properties.

C# supports functional programming concepts, though it's primarily an object-oriented language. Here are the main functional programming features supported in C#:

First-class functions: lambda expressions, delegates, method references
Immutability: records, immutable collections, readonly members
Pure functions: methods without side effects, deterministic outputs
Higher-order functions: LINQ operations, methods that take functions as parameters
Pattern matching: switch expressions, property patterns, type patterns
Expression trees: represent code as data, used extensively in LINQ providers

This article will not discuss the basics of functional programming, as you can find numerous resources on this topic. Instead, it will talk about functional programming in C# applied to algebra, numbers, the Euclidean plane, and fractals. The examples provided in this article will start from simple to more complex but always illustrated in a simple, straightforward and easy-to-understand manner.

Development Environment

To run the source code, you will need to install Visual Studio 2022. Once installed, clone the GitHub repository:

git clone https://github.com/aelassas/functional-cs.git

Then open ./functional-cs/Functional.sln with Visual Studio.

Below are the projects available in the solution:

Functional.Core is a class library that contains sets functions and helpers.
Functional.Core.WPF is a WPF class library that contains plane and fractals functions and helpers.
Functional.EuclideanPlane is a WPF application that contains Euclidean Plane and Fractals samples.
Functional.Laziness is a Console application that contains Laziness samples.
Functional.Set is a Console application that contains sets samples.
Functional.UnitTests is the unit tests project.

To run numbers demo, run Functional.Set project.

To run Euclidean plane and fractals demos, run Functional.EuclideanPlane project.

To run laziness demo, run Functional.Laziness project.

To run unit tests, run the following command:

cd functional-cs/tests/Functional.UnitTests
dotnet test

Representing Data Through Functions

Let S be any set of elements a, b, c ... (for instance, the books on the table, or the videos in YouTube, or the points of the Euclidean plane) and let S' be any subset of these elements (for instance, the green books on the table, or the cultural videos in YouTube, or the points in the circle of radius 1 centered at the origin of the Euclidean plane).

The Characteristic Function S'(x) of the set S' is a function which associates either true or false with each element x of S.

S'(x) = true if x is in S'
S'(x) = false if x is not in S'

Let S be the set of books on the table and let S' be the set of green books on the table. Let a and b be two green books, and let c and d be two red books on the table. Then:

S'(a) = S'(b) = true
S'(c) = S'(d) = false

Let S be the set of the videos in YouTube and let S' be the set of cultural videos in YouTube. Let a and b be two cultural videos in YouTube, and c and d be two non-cultural videos in YouTube. Then:

S'(a) = S'(b) = true
S'(c) = S'(d) = false

Let S be the set of the points in the Euclidean plane and let S' be the set of the points in the circle of radius 1 centered at the origin of the Euclidean plane (0, 0) (unit circle). Let a and b be two points in the unit circle, and let c and d be two points in a circle of radius 2 centered at the origin of the Euclidean plane. Then:

S'(a) = S'(b) = true
S'(c) = S'(d) = false

Thus, any set S' can always be represented by its Characteristic Function. A function that takes as argument an element and returns true if this element is in S', false otherwise. In other words, a set (abstract data type) can be represented through a Predicate in C#.

Predicate<T> set;

In the next sections, we will see how to represent some fundamental sets in the algebra of sets through C# in a functional way, then we will define generic binary operations on sets. We will then apply these operations on numbers then on subsets of the Euclidean Plane. Sets are abstract data structures, the subsets of numbers and the subsets of the Euclidean plane are the representation of abstract data-structures, and finally the binary operations are the generic logics that works on any representation of the abstract data structures.

Sets

This section introduces the representation of some fundamental sets in the algebra of sets through C#.

Empty Set

Let E be the empty set and Empty its Characteristic function. In algebra of sets, E is the unique set having no elements. Therefore, Empty can be defined as follows:

Empty(x) = false if x is in E
Empty(x) = false if x is not in E

Thus, the representation of E in C# can be defined as follows:

public static Predicate<T> Empty<T>() => _ => false;

In algebra of sets, Empty is represented as follows:

Thus, running the code below:

Console.WriteLine("\nEmpty set:");
Console.WriteLine("Is 7 in {{}}? {0}", Empty<int>()(7));

gives the following results:

Set All

Let S be a set and S' be the subset of S that contains all the elements and All its Characteristic function. In algebra of sets, S' is the full set that contains all the elements. Therefore, All can be defined like this:

All(x) = true if x is in S

Thus, the representation of S' in C# can be defined as follows:

public static Predicate<T> All<T>() => _ => true;

In algebra of sets, All is represented as follows:

Thus, running the code below:

Console.WriteLine("Is 7 in the integers set? {0}", All<int>()(7));

gives the following results:

Singleton Set

Let E be the Singleton set and Singleton its Characteristic function. In algebra of sets, E also known as unit set, or 1-tuple is a set with exactly one element e. Therefore, Singleton can be defined as follows:

Singleton(x) = true if x is e
Singleton(x) = false if x is not e

Thus, the representation of E in C# can be defined as follows:

public static Predicate<T> Singleton<T>(T e) where T : notnull => x => e.Equals(x);

Thus, running the code below:

Console.WriteLine("Is 7 in the singleton {{0}}? {0}", Singleton(0)(7));
Console.WriteLine("Is 7 in the singleton {{7}}? {0}", Singleton(7)(7));

gives the following results:

Other Sets

This section presents subsets of the integers set.

Even numbers

Let E be the set of even numbers and Even its Characteristic function. In mathematics, an even number is a number which is a multiple of two. Therefore, Even can be defined as follows:

Even(x) = true if x is a multiple of 2
Even(x) = false if x is not a multiple of 2

Thus, the representation of E in C# can be defined as follows:

Predicate<int> even = i => i % 2 == 0;

Thus, running the code below:

Console.WriteLine("Is {0} even? {1}", 99, even(99));
Console.WriteLine("Is {0} even? {1}", 998, even(998));

gives the following results:

Odd Numbers

Let E be the set of odd numbers and Odd its Characteristic function. In mathematics, an odd number is a number which is not a multiple of two. Therefore, Odd can be defined as follows:

Odd(x) = true if x is not a multiple of 2
Odd(x) = false if x is a multiple of 2

Thus, the representation of E in C# can be defined as follows:

Predicate<int> odd = i => i % 2 == 1;

Thus, running the code below:

Console.WriteLine("Is {0} odd? {1}", 99, odd(99));
Console.WriteLine("Is {0} odd? {1}", 998, odd(998));

gives the following results:

Multiples of 3

Let E be the set of multiples of 3 and MultipleOfThree its Characteristic function. In mathematics, a multiple of 3 is a number divisible by 3. Therefore, MultipleOfThree can be defined as follows:

MultipleOfThree(x) = true if x is divisible by 3
MultipleOfThree(x) = false if x is not divisible by 3

Thus, the representation of E in C# can be defined as follows:

Predicate<int> multipleOfThree = i => i % 3 == 0;

Thus, running the code below:

Console.WriteLine("Is {0} a multiple of 3? {1}", 99, multipleOfThree(99));
Console.WriteLine("Is {0} a multiple of 3? {1}", 998, multipleOfThree(998));

gives the following results:

Multiples of 5

Let E be the set of multiples of 5 and MultipleOfFive its Characteristic function. In mathematics, a multiple of 5 is a number divisible by 5. Therefore, MultipleOfFive can be defined as follows:

MultipleOfFive(x) = true if x is divisible by 5
MultipleOfFive(x) = false if x is not divisible by 5

Thus, the representation of E in C# can be defined as follows:

Predicate<int> multipleOfFive = i => i % 5 == 0;

Thus, running the code below:

Console.WriteLine("Is {0} a multiple of 5? {1}", 15, multipleOfFive(15));
Console.WriteLine("Is {0} a multiple of 5? {1}", 998, multipleOfFive(998));

gives the following results:

Prime Numbers

A long time ago, when I was playing with Project Euler problems, I had to resolve the following one:

By listing the first six prime numbers: 2, 3, 5, 7, 11, and 13, 
we can see that the 6th prime is 13.
What is the 10 001st prime number?

To resolve this problem, I first had to write a fast algorithm that checks whether a given number is prime or not. Once the algorithm was written, I wrote an iterative algorithm that iterates through primes until the 10 001st prime number was found. Nevertheless, is the next iterative algorithm really necessary? You will see.

The algorithm that checks whether a given number is prime or not is the Characteristical function of the primes set.

Let E be the set of primes and Prime its Characteristic function. In mathematics, a prime is a natural number greater than 1 that has no positive divisors other than 1 and itself. Therefore, Prime can be defined as follows:

Prime(x) = true if x is prime
Prime(x) = false if x is not prime

Thus, the representation of E in C# can be defined as follows:

Predicate<int> prime = IsPrime;

where IsPrime is a method that checks whether a given number is prime or not.

static bool IsPrime(int i)
{
    if (i == 1) return false;            // 1 is not prime
    if (i < 4) return true;              // 2 and 3 are primes
    if ((i >> 1) * 2 == i) return false; // multiples of 2 are not prime
    if (i < 9) return true;              // 5 and 7 are primes
    if (i % 3 == 0) return false;        // multiples of 3 are not primes

    // If a divisor less than or equal to sqrt(i) is found,
    // then i is not prime
    int sqrt = (int)Math.Sqrt(i);
    for (int d = 5; d <= sqrt; d += 6)
    {
        if (i % d == 0) return false;
        if (i % (d + 2) == 0) return false;
    }

    // Otherwise i is prime
    return true;
}

Thus, running the code below to resolve our problem:

int p = Primes(prime).Skip(10000).First();
Console.WriteLine("The 10 001st prime number is {0}", p);

where Primes is defined below:

static IEnumerable <int> Primes(Predicate<int> prime)
{
    yield return 2;

    int p = 3;
    while (true)
    {
        if (prime(p)) yield return p;
        p += 2;
    }
}

gives the following results:

Binary Operations

This section presents several fundamental operations for constructing new sets from given sets and for manipulating sets. Below is the Venn diagram in the algebra of sets.

Union

Let E and F be two sets. The union of E and F, denoted by E U F is the set of all elements which are members of either E and F.

Let Union be the union operation. Thus, the Union operation can be implemented as follows in C#:

public static Predicate<T> Union<T>(this Predicate<T> e, Predicate<T> f)
  => x => e(x) || f(x);

As you can see, Union is an extension function on the Characteristic function of a set. All the operations will be defined as extension functions on the Characteristic function of a set. Thereby, running the code below:

Console.WriteLine("Is 7 in the union of Even and Odd Integers Set? {0}", Even.Union(Odd)(7));

gives the following results:

Intersection

Let E and F be two sets. The intersection of E and F, denoted by E n F is the set of all elements which are members of both E and F.

Let Intersection be the intersection operation. Thus, the Intersection operation can be implemented as follows in C#:

public static Predicate<T> Intersection<T>(this Predicate<T> e, Predicate<T> f)
  => x => e(x) && f(x);

As you can see, Intersection is an extension function on the Characteristic function of a set. Thereby, running the code below:

Predicate<int> multiplesOfThreeAndFive = multipleOfThree.Intersection(multipleOfFive);
Console.WriteLine("Is 15 a multiple of 3 and 5? {0}", multiplesOfThreeAndFive(15));
Console.WriteLine("Is 10 a multiple of 3 and 5? {0}", multiplesOfThreeAndFive(10));

gives the following results:

Cartesian Product

Let E and F be two sets. The cartesian product of E and F, denoted by E × F is the set of all ordered pairs (e, f) such that e is a member of E and f is a member of F.

Let CartesianProduct be the cartesian product operation. Thus, the CartesianProduct operation can be implemented as follows in C#:

public static Func<T1, T2, bool> 
       CartesianProduct<T1, T2>(this Predicate<T1> e, Predicate<T2> f) => (x, y)
  => e(x) && f(y);

As you can see, CartesianProduct is an extension function on the Characteristic function of a set. Thereby, running the code below:

Func<int, int, bool> cartesianProduct = multipleOfThree.CartesianProduct(multipleOfFive);
Console.WriteLine("Is (9, 15) in MultipleOfThree x MultipleOfFive? {0}", 
                                 cartesianProduct(9, 15));

gives the following results:

Complements

Let E and F be two sets. The relative complement of F in E, denoted by E \ F is the set of all elements which are members of E but not members of F.

Let Complement be the relative complement operation. Thus, the Complement operation can be implemented as follows in C#:

public static Predicate<T> Complement<T>(this Predicate<T> e, Predicate<T> f)
  => x => e(x) && !f(x);

As you can see, Complement is an extension method on the Characteristic function of a set. Thereby, running the code below:

Console.WriteLine("Is 15 in MultipleOfThree \\ MultipleOfFive set? {0}", 
          multipleOfThree.Complement(multipleOfFive)(15));
Console.WriteLine("Is 9 in MultipleOfThree \\ MultipleOfFive set? {0}", 
          multipleOfThree.Complement(multipleOfFive)(9));

gives the following results:

Symmetric Difference

Let E and F be two sets. The symmetric difference of E and F, denoted by E Δ F is the set of all elements which are members of either E and F but not in the intersection of E and F.

Let SymmetricDifference be the symmetric difference operation. Thus, the SymmetricDifference operation can be implemented in two ways in C#. A trivial way is to use the union and complement operations as follows:

public static Predicate<T> SymmetricDifferenceWithoutXor<T>
              (this Predicate<T> e, Predicate<T> f)
  => Union(e.Complement(f), f.Complement(e));

Another way is to use the XOR binary operation as follows:

public static Predicate<T> SymmetricDifferenceWithXor<T>
              (this Predicate<T> e, Predicate<T> f)
  => x => e(x) ^ f(x);

As you can see, SymmetricDifferenceWithoutXor and SymmetricDifferenceWithXor are extension methods on the Characteristic function of a set. Thereby, running the code below:

// SymmetricDifference without XOR
Console.WriteLine("\nSymmetricDifference without XOR:");
Predicate<int> sdWithoutXor = prime.SymmetricDifferenceWithoutXor(even);
Console.WriteLine("Is 2 in the symmetric difference of prime and even Sets? {0}", 
                   sdWithoutXor(2));
Console.WriteLine("Is 4 in the symmetric difference of prime and even Sets? {0}", 
                   sdWithoutXor(4));
Console.WriteLine("Is 7 in the symmetric difference of prime and even Sets? {0}", 
                   sdWithoutXor(7));

// SymmetricDifference with XOR
Console.WriteLine("\nSymmetricDifference with XOR:");
Predicate<int> sdWithXor = prime.SymmetricDifferenceWithXor(even);
Console.WriteLine("Is 2 in the symetric difference of prime and even Sets? {0}", 
                   sdWithXor(2));
Console.WriteLine("Is 4 in the symmetric difference of prime and even Sets? {0}", 
                   sdWithXor(4));
Console.WriteLine("Is 7 in the symmetric difference of prime and even Sets? {0}", 
                   sdWithXor(7));

gives the following results:

Other Operations

This section presents other useful binary operations on sets.

Contains

Let Contains be the operation that checks whether or not an element is in a set. This operation is an extension function on the Characteristic function of a set that takes as parameter an element and returns true if the element is in the set, false otherwise.

Thus, this operation is defined as follows in C#:

public static bool Contains<T>(this Predicate<T> e, T x) => e(x);

Therefore, running the code below:

Console.WriteLine("Is 7 in the singleton {{0}}? {0}", Singleton(0).Contains(7));
Console.WriteLine("Is 7 in the singleton {{7}}? {0}", Singleton(7).Contains(7));

gives the following result:

Add

Let Add be the operation that adds an element to a set. This operation is an extension function on the Characteristic function of a set that takes as parameter an element and adds it to the set.

Thus, this operation is defined as follows in C#:

public static Predicate<T> Add<T>(this Predicate<T> s, T e) where T : notnull
  => x => x.Equals(e) || s(x);

Therefore, running the code below:

Console.WriteLine("Is 7 in {{0, 7}}? {0}", Singleton(0).Add(7)(7));
Console.WriteLine("Is 0 in {{1, 0}}? {0}", Singleton(1).Add(0)(0));
Console.WriteLine("Is 7 in {{19, 0}}? {0}", Singleton(19).Add(0)(7));

gives the following result:

Remove

Let Remove be the operation that removes an element from a set. This operation is an extension function on the Characteristic function of a set that takes as parameter an element and removes it from the set.

Thus, this operation is defined as follows in C#:

public static Predicate<T> Remove<T>(this Predicate<T> s, T e) where T : notnull
  => x => !x.Equals(e) && s(x);

Therefore, running the code below:

Console.WriteLine("Is 7 in {{}}? {0}", Singleton(0).Remove(0)(7));
Console.WriteLine("Is 0 in {{}}? {0}", Singleton(7).Remove(7)(0));

gives the following result:

For Those Who Want to Go Further

You can see how easily we can do some algebra of sets in C# through functional programming. In the previous sections was shown the most fundamental definitions. But, if you want to go further, you can think about:

Relations over sets
Abstract algebra, such as monoids, groups, fields, rings, K-vectorial spaces and so on
Inclusion-exclusion principle
Russell's paradox
Cantor's paradox
Dual vector space
Theorems and Corollaries

Euclidean Plane

In the previous section, the fundamental concepts on sets were implemented in C#. In this section, we will practice the concepts implemented on the set of plane points (Euclidean plane).

Drawing a Disk

A disk is a subset of a plane bounded by a circle. There are two types of disks. Closed disks which are disks that contain the points of the circle that constitutes its boundary, and Open disks which are disks that do not contain the points of the circle that constitutes its boundary.

In this section, we will set up the Characterstic function of the Closed disk and draw it in WPF.

To set up the Characterstic function, we need first a function that calculates the Euclidean Distance between two points in the plane. This function is implemented as follows:

private static double EuclidianDistance(Point point1, Point point2)
  => Math.Sqrt(Math.Pow(point1.X - point2.X, 2) + Math.Pow(point1.Y - point2.Y, 2));

where Point is a struct defined in the System.Windows namespace. This formula is based on Pythagoras' Theorem.

where c is the Euclidean distance, a² is (point1.X - point2.X)² and b² is (point1.Y - point2.Y)².

Let Disk be the Characteristic function of a closed disk. In algebra of sets, the definition of a closed disk in the reals set is as follows:

where a and b are the coordinates of the center and R the radius.

Thus, the implementation of Disk in C# is as follows:

public static Predicate<Point> Disk(Point center, double radius)
  => p => EuclidianDistance(center, p) <= radius;

In order to view the set in a result, I decided to implement a function Draw that draws a set in the Euclidean plane. I chose WPF and thus used the System.Windows.Controls.Image as a canvas and a Bitmap as the context.

Thus, I've built the Euclidean plane illustrated below through the method Draw.

Below the implementation of the method.

public static void Draw(this Predicate<Point> set, Image plane)
{
    var bitmap = new Bitmap((int)plane.Width, (int)plane.Height);

    //
    // Graph drawing
    //
    double semiWidth = plane.Width / 2;
    double semiHeight = plane.Height / 2;

    double xMin = -semiWidth;
    double xMax = +semiWidth;
    double yMin = -semiHeight;
    double yMax = +semiHeight;

    for (int x = 0; x < bitmap.Height; x++)
    {
        double xp = xMin + x * (xMax - xMin) / plane.Width;

        for (int y = 0; y < bitmap.Width; y++)
        {
            double yp = yMax - y * (yMax - yMin) / plane.Height;

            if (set(new Point(xp, yp)))
            {
                bitmap.SetPixel(x, y, Color.Black);
            }
        }
    }

    plane.Source = Imaging.CreateBitmapSourceFromHBitmap(
        bitmap.GetHbitmap(),
        IntPtr.Zero,
        Int32Rect.Empty,
        BitmapSizeOptions.FromWidthAndHeight(bitmap.Width, bitmap.Height));
}

In the Draw method, a bitmap having the same width and same height as the Euclidean plane container is created. Then each point in pixels (x,y) of the bitmap is replaced by a black point if it belongs to the set. xMin, xMax, yMin and yMax are the bounding values illustrated in the figure of the Euclidean plane above.

As you can see, Draw is an extension function on the Characteristic function of a set of points. Therefore, running the code below:

Plane.Disk(new Point(0, 0), 20).Draw(PlaneCanvas);

gives the following result:

Drawing Horizontal and Vertical Half-Planes

A horizontal or a vertical half-plane is either of the two subsets into which a plane divides the Euclidean space. A horizontal half-plane is either of the two subsets into which a plane divides the Euclidean space through a line perpendicular with the Y axis like in the figure above. A vertical half-plane is either of the two subsets into which a plane divides the Euclidean space through a line perpendicular with the X axis.

In this section, we will set up the Characteristic functions of the horizontal and vertical half-planes, draw them in WPF and see what we can do if we combine them with the disk subset.

Let HorizontalHalfPlane be the Characteristic function of a horizontal half-plane. The implementation of HorizontalHalfPlane in C# is as follows:

public static Predicate<Point> HorizontalHalfPlane(double y, bool lowerThan)
  => p => lowerThan ? p.Y <= y : p.Y >= y;

Thus, running the code below:

Plane.HorizontalHalfPlane(0, true).Draw(PlaneCanvas);

gives the following result:

Let VerticalHalfPlane be the Characteristic function of a vertical half-plane. The implementation of VerticalHalfPlane in C# is as follows:

public static Predicate<Point> VerticalHalfPlane(double x, bool lowerThan)
  => p => lowerThan ? p.X <= x : p.X >= x;

Thus, running the code below:

Plane.VerticalHalfPlane(0, false).Draw(PlaneCanvas);

gives the following result:

In the first section of the article, we set up basic binary operations on sets. Thus, by combining the intersection of a disk and a half-plane for example, we can draw the half-disk subset.

Therefore, running the sample below:

Plane.VerticalHalfPlane(0, false).Intersection(Plane.Disk(new Point(0, 0), 20)).Draw(PlaneCanvas);

gives the following result:

Functions

This section presents functions on the sets in the Euclidean plane.

Translate

Let Translate be the function that translates a point in the plane. In Euclidean geometry, Translate is a function that moves a given point a constant distance in a specified direction. Thus the implementation in C# is as follows:

private static Func<Point, Point> Translate(double deltax, double deltay)
  => p => new Point(p.X + deltax, p.Y + deltay);

where (deltax, deltay) is the constant vector of the translation.

Let TranslateSet be the function that translates a set in the plane. This function is simply implemented as follows in C#:

public static Predicate<Point> TranslateSet
       (this Predicate<Point> set, double deltax, double deltay)
  => x => set(Translate(-deltax, -deltay)(x));

TranslateSet is an extension function on a set. It takes as parameters deltax which is the delta distance in the first Euclidean dimension and deltay which is the delta distance in the second Euclidean dimension. If a point P (x, y) is translated in a set S, then its coordinates will change to (x', y') = (x + delatx, y + deltay). Thus, the point (x' - delatx, y' - deltay) will always belong to the set S. In set algebra, TranslateSet is called isomorph, in other words, the set of all translations forms the translation group T, which is isomorphic to the space itself. This explains the main logic of the function.

Thus, running the code below in our WPF application:

TranslateDiskAnimation();

where TranslateDiskAnimation is described below:

private const double Delta = 50;
private double _diskDeltay;
private readonly Predicate<Point> _disk = Plane.Disk(new Point(0, -170), 80);

private void TranslateDiskAnimation()
{
    DispatcherTimer diskTimer = new DispatcherTimer 
                    { Interval = new TimeSpan(0, 0, 0, 1, 0) };
    diskTimer.Tick += TranslateTimer_Tick;
    diskTimer.Start();
}

private void TranslateTimer_Tick(object? sender, EventArgs e)
{
    _diskDeltay = _diskDeltay <= plan.Height ? _diskDeltay + Delta : Delta;
    Predicate<Point> translatedDisk = _diskDeltay <= plan.Height ? 
                                      _disk.TranslateSet(0, _diskDeltay) : _disk;
    translatedDisk.Draw(PlaneCanvas);
}

gives the following result:

Homothety

Let Scale be the function that sends any point M to another point N such that the segment SN is on the same line as SM, but scaled by a factor λ. In algebra of sets, Scale is formulated as follows:

Thus the implementation in C# is as follows:

private static Func<Point, Point> Scale
    (double deltax, double deltay, double lambdax, double lambday)
  => p => new Point(lambdax * p.X + deltax, lambday * p.Y + deltay);

where (deltax, deltay) is the constant vector of the translation and (lambdax, lambday) is the λ vector.

Let ScaleSet be the function that applies an homothety on a set in the plan. This function is simply implemented as follows in C#:

public static Predicate<Point> ScaleSet
    (this Predicate<Point> set, double deltax, double deltay, double lambdax,
    double lambday) =>
    x => set(Scale(-deltax / lambdax, -deltay / lambday, 1 / lambdax, 1 / lambday)(x));

ScaleSet is an extension function on a set. It takes as parameters deltax which is the delta distance in the first Euclidean dimension, deltay which is the delta distance in the second Euclidean dimension and (lambdax, lambday) which is the constant factor vector λ. If a point P (x, y) is transformed through ScaleSet in a set S, then its coordinates will change to (x', y') = (lambdax * x + delatx, lambday * y + deltay). Thus, the point ((x'- delatx)/lambdax, (y' - deltay)/lambday) will always belong to the set S, If λ is different from the vector 0, of course. In algebra of sets, ScaleSet is called isomorph, in other words the set of all homotheties forms the Homothety group H, which is isomorphic to the space itself \ {0}. This explains the main logic of the function.

Thus, running the code below in our WPF application:

ScaleDiskAnimation();

where ScaleDiskAnimation is described below:

private const double Delta = 50;
private double _lambdaFactor = 1;
private double _diskScaleDeltay;
private readonly Predicate<Point> _disk2 = Plane.Disk(new Point(0, -230), 20);

private void ScaleDiskAnimation()
{
    DispatcherTimer scaleTimer = new DispatcherTimer 
        { Interval = new TimeSpan(0, 0, 0, 1, 0) };
    scaleTimer.Tick += ScaleTimer_Tick;
    scaleTimer.Start();
}

private void ScaleTimer_Tick(object? sender, EventArgs e)
{
    _diskScaleDeltay = _diskScaleDeltay <= plan.Height ? 
                       _diskScaleDeltay + Delta : Delta;
    _lambdaFactor = _diskScaleDeltay <= plan.Height ? _lambdaFactor + 0.5 : 1;
    Predicate<Point> scaledDisk = _diskScaleDeltay <= plan.Height
                                        ? _disk2.ScaleSet(0, _diskScaleDeltay, 
                                          _lambdaFactor, 1)
                                        : _disk2;
    scaledDisk.Draw(PlaneCanvas);
}

gives the following result:

Rotate

Let Rotation be the function that rotates a point with an angle θ. In matrix algebra, Rotation is formulated as follows:

where (x', y') are the co-ordinates of the point after rotation, and the formula for x' and y' is as follows:

The demonstration of this formula is very simple. Have a look at this rotation.

Below the demonstration:

Thus the implementation in C# is as follows:

private static Func<Point, Point> Rotate(double theta)
  => p => new Point(p.X * Math.Cos(theta) - p.Y * Math.Sin(theta),
                    p.X * Math.Sin(theta) + p.Y * Math.Cos(theta));

Let RotateSet be the function that applies a rotation on a set in the plane with the angle θ. This function is simply implemented as follow in C#.

public static Predicate<Point> RotateSet(this Predicate<Point> set, double theta)
  => p => set(Rotate(-theta)(p));

RotateSet is an extension function on a set. It takes as parameter theta which is the angle of the rotation. If a point P (x, y) is transformed through RotateSet in a set S, then its coordinates will change to (x', y') = (x * cos(θ) - y * sin(θ), x * cos(θ) + y * sin(θ)). Thus, the point (x' * cos(θ) + y' * sin(θ), x' * cos(θ) - y' * sin(θ)) will always belong to the set S. In algebra of sets, RotateSet is called isomorph, in other words, the set of all rotations forms the Rotation group R, which is isomorphic to the space itself. This explains the main logic of the function.

Thus, running the code below in our WPF application:

RotateHalfPlaneAnimation();

where RotateHalfPlaneAnimation is described below:

private double _theta;
private const double TWO_PI = 2 * Math.PI;
private const double HALF_PI = Math.PI / 2;
private readonly Predicate<Point> _halfPlane = Plane.VerticalHalfPlane(220, false);

private void RotateHalfPlaneAnimation()
{
    DispatcherTimer rotateTimer = 
          new DispatcherTimer { Interval = new TimeSpan(0, 0, 0, 1, 0) };
    rotateTimer.Tick += RotateTimer_Tick;
    rotateTimer.Start();
}

private void RotateTimer_Tick(object? sender, EventArgs e)
{
    _halfPlane.RotateSet(_theta).Draw(PlaneCanvas);
    _theta += HALF_PI;
    _theta %= TWO_PI;
}

gives the following result:

For Those Who Want to Go Further

Very simple, isn't it? For those who want to go further, you can explore these:

Ellipse
Three-dimensional Euclidean space
Ellipsoid
Paraboloid
Hyperboloid
Spherical harmonics
Superellipsoid
Haumea
Homoeoid
Focaloid

Fractals

Fractals are sets that have a fractal dimension that usually exceeds their topological dimension and may fall between the integers. For example, the Mandelbrot set is a fractal defined by a family of complex quadratic polynomials:

Pc(z) = z^2 + c

where c is a complex. The Mandelbrot fractal is defined as the set of all points c such that the above sequence does not escape to infinity. In algebra of sets, this is formulated as follows:

A Mandelbrot set is illustrated above.

Fractals (abstract data type) can always be represented as follows in C#:

Func<Complex, Complex> fractal;

Complex Numbers and Drawing

In order to be able to draw fractals, I needed to manipulate Complex numbers. Thus, I've used Meta.numerics library. I also needed an utility to draw complex numbers in a Bitmap, thus I used ColorMap and ClorTriplet classes that are available in this CodeProject article.

Mandelbrot Fractal

I've created a Mandelbrot (abstract data type representation) P(z) = z^2 + c that is available below.

public static Func<Complex, Complex, Complex> MandelbrotFractal() => (c, z) => z * z + c;

In order to be able to draw Complex numbers, I needed to update the Draw function. Thus, I created an overload of the Draw function that uses ColorMap and ClorTriplet classes. Below is the implementation in C#.

public static void Draw(this Func<Complex, Complex> fractal, Image plane)
{
    var bitmap = new Bitmap((int)plane.Width, (int)plane.Height);

    const double reMin = -3.0;
    const double reMax = +3.0;
    const double imMin = -3.0;
    const double imMax = +3.0;

    for (int x = 0; x < plane.Width; x++)
    {
        double re = reMin + x * (reMax - reMin) / plane.Width;
        for (int y = 0; y < plane.Height; y++)
        {
            double im = imMax - y * (imMax - imMin) / plane.Height;

            var z = new Complex(re, im);
            Complex fz = fractal(z);

            if (Double.IsInfinity(fz.Re) || Double.IsNaN(fz.Re) || 
                                            Double.IsInfinity(fz.Im) ||
                Double.IsNaN(fz.Im))
            {
                continue;
            }

            ColorTriplet hsv = ColorMap.ComplexToHsv(fz);

            ColorTriplet rgb = ColorMap.HsvToRgb(hsv);
            var r = (int)Math.Truncate(255.0 * rgb.X);
            var g = (int)Math.Truncate(255.0 * rgb.Y);
            var b = (int)Math.Truncate(255.0 * rgb.Z);
            Color color = Color.FromArgb(r, g, b);

            bitmap.SetPixel(x, y, color);
        }
    }

    plane.Source = Imaging.CreateBitmapSourceFromHBitmap(
        bitmap.GetHbitmap(),
        IntPtr.Zero,
        Int32Rect.Empty,
        BitmapSizeOptions.FromWidthAndHeight(bitmap.Width, bitmap.Height));
}

Thus, running the code below:

Plane.MandelbrotFractal().Draw(PlaneCanvas, 20, 1.5);

gives the following result:

Newton Fractal

I've also created a Newton Fractal (abstract data type representation) P(z) = z^3 - 2*z + 2 that is available below:

public static Func<Complex, Complex> NewtonFractal() => z => z * z * z - 2 * z + 2;

Thus, running the code below:

Plane.NewtonFractal().Draw(PlaneCanvas);

gives the following result:

For Those Who Want to Go Further

For those who want to go further, you can explore these:

Mandelbrot Fractals
Julia Fractals
Other Newton Fractals
Other Fractals

Introduction to Laziness

In this section, we will see how to make a type Lazy.

Lazy evaluation is an evaluation strategy which delays the evaluation of an expression until its value is needed and which also avoids repeated evaluations. The sharing can reduce the running time of certain functions by an exponential factor over other non-strict evaluation strategies, such as call-by-name. Below the benefits of Lazy evaluation.

Performance increases by avoiding needless calculations, and error conditions in evaluating compound expressions
The ability to construct potentially infinite data structure: We can easily create an infinite set of integers, for example, through a function (see the example on prime numbers in the Sets section)
The ability to define control flow (structures) as abstractions instead of primitives

Let's have a look at the code below:

public class MyLazy<T>
{
    #region Fields

    private readonly Func<T> _f;
    private bool _hasValue;
    private T? _value;

    #endregion

    #region Constructors

    public MyLazy(Func<T> f)
    {
        _f = f;
    }

    #endregion

    #region Operators

    //
    // Use objects of type MyLazy<T> as objects of type T 
    // through implicit keyword
    //
    public static implicit operator T?(MyLazy<T?> lazy)
    {
        if (!lazy._hasValue)
        {
            lazy._value = lazy._f();
            lazy._hasValue = true;
        }

        return lazy._value;
    }

    #endregion
}

MyLazy<T> is a generic class that contains the following fields:

_f: A function for lazy evaluation that returns a value of type T
_value: A value of type T (frozen value)
_hasValue: A boolean that indicates whether the value has been calculated or not

In order to use objects of type MyLazy<T> as objects of type T, the implicit keyword is used. The evaluation is done at type casting time, this operation is called thaw.

Thus, running the code below:

var myLazyRandom = new MyLazy<double>(GetRandomNumber);
double myRandomX = myLazyRandom;
Console.WriteLine("\n Random with MyLazy<double>: {0}", myRandomX);

where GetRandomNumber returns a random double as follows:

static double GetRandomNumber() => new Random().NextDouble();

gives the following output:

The .NET Framework 4 introduced a class System.Lazy<T> for lazy evaluation. This class returns the value through the property Value. Running the code below:

var lazyRandom = new Lazy<double>(GetRandomNumber);
double randomX = lazyRandom;

gives a compilation error because the type Lazy<T> is different from the type double.

To work with the value of the class System.Lazy<T>, the property Value has to be used as follows:

var lazyRandom = new Lazy<double>(GetRandomNumber);
double randomX = lazyRandom.Value;
Console.WriteLine("\n Random with System.Lazy<double>.Value: {0}", randomX);

which gives the following output:

The .NET Framework 4 also introduced ThreadLocal and LazyInitializer for Lazy evaluation.

Unit Tests

Below are the unit tests for sets of numbers using xUnit.

using Functional.Core;

namespace Functional.UnitTests;

public class SetUnitTest
{
    [Fact]
    public void TestEmptySet()
    {
        Assert.False(Set.Empty<int>()(7));
    }

    [Fact]
    public void TestSetAll()
    {
        Assert.True(Set.All<int>()(7));
    }

    [Fact]
    public void TestSingleton()
    {
        Assert.False(Set.Singleton(0)(7));
        Assert.True(Set.Singleton(7)(7));
    }

    [Fact]
    public void TestEvenNumbers()
    {
        Assert.False(Set.Even(99));
        Assert.True(Set.Even(998));
    }

    [Fact]
    public void TestOddNumbers()
    {
        Assert.True(Set.Odd(99));
        Assert.False(Set.Odd(998));
    }

    [Fact]
    public void TestMultiplesOfThree()
    {
        Assert.True(Set.MultipleOfThree(99));
        Assert.False(Set.MultipleOfThree(998));
    }

    [Fact]
    public void TestMultiplesOfFive()
    {
        Assert.True(Set.MultipleOfThree(15));
        Assert.False(Set.MultipleOfThree(998));
    }

    [Fact]
    public void TestPrimes()
    {
        Assert.False(Set.Prime(0));
        Assert.True(Set.Prime(2));
        Assert.False(Set.Prime(4));
        Assert.Equal(104743, Set.Primes(Set.Prime).Skip(10000).First());
    }

    [Fact]
    public void TestUnion()
    {
        Assert.True(Set.Even.Union(Set.Odd)(7));
    }

    [Fact]
    public void TestIntersection()
    {
        Predicate<int> multiplesOfThreeAndFive = Set.MultipleOfThree.Intersection(Set.MultipleOfFive);
        Assert.True(multiplesOfThreeAndFive(15));
        Assert.False(multiplesOfThreeAndFive(10));
    }

    [Fact]
    public void TestCartesianProduct()
    {
        Func<int, int, bool> cartesianProduct = Set.MultipleOfThree.CartesianProduct(Set.MultipleOfFive);
        Assert.True(cartesianProduct(9, 15));
        Assert.False(cartesianProduct(10, 15));
    }

    [Fact]
    public void TestComplement()
    {
        Assert.False(Set.MultipleOfThree.Complement(Set.MultipleOfFive)(15));
        Assert.True(Set.MultipleOfThree.Complement(Set.MultipleOfFive)(9));
    }

    [Fact]
    public void TestSymmetricDifferenceWithoutXor()
    {
        Predicate<int> sdWithoutXor = Set.Prime.SymmetricDifferenceWithoutXor(Set.Even);
        Assert.False(sdWithoutXor(2));
        Assert.True(sdWithoutXor(4));
        Assert.True(sdWithoutXor(7));
    }

    [Fact]
    public void TestSymmetricDifferenceWithXor()
    {
        Predicate<int> sdWithXor = Set.Prime.SymmetricDifferenceWithXor(Set.Even);
        Assert.False(sdWithXor(2));
        Assert.True(sdWithXor(4));
        Assert.True(sdWithXor(7));
    }

    [Fact]
    public void TestContains()
    {
        Assert.False(Set.Singleton(0).Contains(7));
        Assert.True(Set.Singleton(7).Contains(7));
    }

    [Fact]
    public void TestAdd()
    {
        Assert.True(Set.Singleton(0).Add(7)(7));
        Assert.True(Set.Singleton(1).Add(0)(0));
        Assert.False(Set.Singleton(19).Add(0)(7));
    }

    [Fact]
    public void TestRemove()
    {
        Assert.False(Set.Singleton(0).Remove(0)(7));
        Assert.False(Set.Singleton(7).Remove(7)(0));
        Assert.False(Set.All<int>().Remove(0)(0));
        Assert.True(Set.All<int>().Remove(0)(7));
    }
}

Below are unit tests for lazy evaluation.

using Functional.Core;

namespace Functional.UnitTests;

public class LazyUnitTest
{
    static double GetRandomNumber() => new Random().NextDouble();

    [Fact]
    public void TestMyLazy()
    {
        var myLazyRandom = new MyLazy<double>(GetRandomNumber);
        double myRandomX = myLazyRandom; // implicit cast
        Assert.NotNull(myLazyRandom);
        Assert.Equal(myRandomX, myLazyRandom);
    }
}

After running the unit tests with the following commands:

cd functional-cs/tests/Functional.UnitTests
dotnet test --verbosity normal /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura

We reach 100% of code coverage. You can generate the coverage report with the following command after running the unit tests:

dotnet tool install -g dotnet-reportgenerator-globaltool
reportgenerator -reports:"./coverage.cobertura.xml" -targetdir:"coveragereport" -reporttypes:Html

The coverage report is written in ./coveragereport folder.

That's it! I hope you enjoyed reading.

From Zero to Storefront: My Journey Building a Car Rental Website and Mobile App

aelassas — Fri, 08 Nov 2024 08:25:14 +0000

Introduction
Tech Stack
Quick Overview
API
Frontend
Mobile App
Admin Dashboard
Points of Interest
Resources

Source code: https://github.com/aelassas/bookcars

Demo: https://bookcars.dynv6.net:3002

Introduction

The idea emerged from a desire to build without boundaries – a fully customizable car rental website and mobile app where every aspect is within your control:

Own the UI/UX: Design unique customer experiences without fighting against template limitations
Control the Backend: Implement custom business logic and data structures that perfectly match the requirements
Master DevOps: Deploy, scale, and monitor the application with preferred tools and workflows
Extend Freely: Add new features and integrations without platform constraints or additional fees

Tech Stack

Here's the tech stack that made it possible:

TypeScript
Node.js
MongoDB
React
MUI
React Native
Expo
Stripe
Docker

I chose React for its powerful rendering capabilities, MongoDB for flexible data modeling, and Stripe for secure payment processing.

React stands out as an excellent choice due to its:

Component-Based Architecture
- Lets you break down complex UIs into smaller, reusable pieces
- Makes code more maintainable and easier to test
- Enables better code organization and reusability
Virtual DOM Performance
- React's virtual DOM efficiently updates only what's necessary
- Results in faster page loads and better user experience
- Reduces unnecessary re-renders
Rich Ecosystem
- Vast library of pre-built components
- Extensive tooling
- Large community for support and resources
Strong Developer Experience
- Hot reloading for immediate feedback
- Excellent debugging tools
- JSX makes writing UI code more intuitive
Industry Support
- Backed by Meta (formerly Facebook)
- Used by many major companies
- Continuous development and improvements
Flexibility
- Works well for both small and large applications
- Can be integrated gradually into existing projects
- Supports multiple rendering strategies (client-side, server-side, static)

Quick overview

In this section, you'll see the main pages of the frontend, the admin dashboard and the mobile app.

Frontend

From the frontend, the user can search for available cars, choose a car and checkout.

Below is the main page of the frontend where the user can choose pickup and drop-off points and time, and search for available cars.

Below is the search result of the main page where the user can choose a car for rental.

Below is the checkout page where the user can set rental options and checkout. If the user is not registered, he can checkout and register at the same time. He will receive a confirmation and activation email to set his password if he is not registered yet.

Below is the sign up page.

Below is the page where the user can see and manage his bookings.

Below is the page where the user can see a booking in detail.

Below is the contact page.

Below is the car rental locations page.

Below is the page where the customer can see and manage his notifications.

There are other pages but these are the main pages of the frontend.

Admin Dashboard

There are three types of users:

Admin: He has full access on the admin dashboard. He can do everything.
Supplier: He has restricted access on the admin dashboard. He can only manage his cars and bookings.
User: He has only access to the frontend and the mobile app. He cannot access the admin dashboard.

The platform is designed to work with multiple suppliers. Each supplier can manage his car fleet and bookings from the admin dashboard. The platform can also work with only one supplier as well.

From the admin dashboard, the admin user can create and manage suppliers, cars, locations, users and bookings.

When the admin user creates a new supplier, the supplier will receive an automatic email for creating his account to access the admin dashboard so he can manage his car fleet and bookings.

Below is the sign in page of the admin dashboard.

Below is the dashboard page of the admin dashboard where admins and suppliers can see and manage bookings.

Below is the page where car fleet is displayed and can be managed.

Below is the page where admins and suppliers can create new cars by providing an image and car info. For car options to be included for free, set 0 for the corresponding car option. Otherwise, set the price of the option or leave it empty if you don't want to include it.

Below is the page where admins and suppliers can edit cars.

Below is the page where admins can manage platform users.

Below is the page where to edit bookings.

There are other pages but these are the main pages of the admin dashboard.

API

The api exposes all functions needed for the admin dashboard, the frontend and the mobile app. The API follow the MVC design pattern. JWT is used for authentication. There are some functions that need authentication such as functions related to managing cars, bookings and customers, and others that do not need authentication such as retrieving locations and available cars for non authenticated users:

./api/src/models/ folder contains MongoDB models.
./api/src/routes/ folder contains Express routes.
./api/src/controllers/ folder contains controllers.
./api/src/middlewares/ folder contains middlewares.
./api/src/config/env.config.ts contains the configuration and TypeScript type definitions.
./api/src/lang/ folder contains localization.
./api/src/app.ts is the main server where routes are loaded.
./api/index.ts is the main entry point of the api.

index.ts is the main entry point of the api:

import 'dotenv/config'
import process from 'node:process'
import fs from 'node:fs/promises'
import http from 'node:http'
import https, { ServerOptions } from 'node:https'
import * as env from './config/env.config'
import * as databaseHelper from './common/databaseHelper'
import app from './app'
import * as logger from './common/logger'

if (
  await databaseHelper.connect(env.DB_URI, env.DB_SSL, env.DB_DEBUG)
  && await databaseHelper.initialize()
) {
  let server: http.Server | https.Server

  if (env.HTTPS) {
    https.globalAgent.maxSockets = Number.POSITIVE_INFINITY
    const privateKey = await fs.readFile(env.PRIVATE_KEY, 'utf8')
    const certificate = await fs.readFile(env.CERTIFICATE, 'utf8')
    const credentials: ServerOptions = { key: privateKey, cert: certificate }
    server = https.createServer(credentials, app)

    server.listen(env.PORT, () => {
      logger.info('HTTPS server is running on Port', env.PORT)
    })
  } else {
    server = app.listen(env.PORT, () => {
      logger.info('HTTP server is running on Port', env.PORT)
    })
  }

  const close = () => {
    logger.info('Gracefully stopping...')
    server.close(async () => {
      logger.info(`HTTP${env.HTTPS ? 'S' : ''} server closed`)
      await databaseHelper.close(true)
      logger.info('MongoDB connection closed')
      process.exit(0)
    })
  }

  ['SIGINT', 'SIGTERM', 'SIGQUIT'].forEach((signal) => process.on(signal, close))
}

app.ts is the main entry point of the api:

import express from 'express'
import compression from 'compression'
import helmet from 'helmet'
import nocache from 'nocache'
import cookieParser from 'cookie-parser'
import i18n from './lang/i18n'
import * as env from './config/env.config'
import cors from './middlewares/cors'
import allowedMethods from './middlewares/allowedMethods'
import supplierRoutes from './routes/supplierRoutes'
import bookingRoutes from './routes/bookingRoutes'
import locationRoutes from './routes/locationRoutes'
import notificationRoutes from './routes/notificationRoutes'
import carRoutes from './routes/carRoutes'
import userRoutes from './routes/userRoutes'
import stripeRoutes from './routes/stripeRoutes'
import countryRoutes from './routes/countryRoutes'
import * as helper from './common/helper'

const app = express()

app.use(helmet.contentSecurityPolicy())
app.use(helmet.dnsPrefetchControl())
app.use(helmet.crossOriginEmbedderPolicy())
app.use(helmet.frameguard())
app.use(helmet.hidePoweredBy())
app.use(helmet.hsts())
app.use(helmet.ieNoOpen())
app.use(helmet.noSniff())
app.use(helmet.permittedCrossDomainPolicies())
app.use(helmet.referrerPolicy())
app.use(helmet.xssFilter())
app.use(helmet.originAgentCluster())
app.use(helmet.crossOriginResourcePolicy({ policy: 'cross-origin' }))
app.use(helmet.crossOriginOpenerPolicy())

app.use(nocache())
app.use(compression({ threshold: 0 }))
app.use(express.urlencoded({ limit: '50mb', extended: true }))
app.use(express.json({ limit: '50mb' }))

app.use(cors())
app.options('*', cors())
app.use(cookieParser(env.COOKIE_SECRET))
app.use(allowedMethods)

app.use('/', supplierRoutes)
app.use('/', bookingRoutes)
app.use('/', locationRoutes)
app.use('/', notificationRoutes)
app.use('/', carRoutes)
app.use('/', userRoutes)
app.use('/', stripeRoutes)
app.use('/', countryRoutes)

i18n.locale = env.DEFAULT_LANGUAGE

await helper.mkdir(env.CDN_USERS)
await helper.mkdir(env.CDN_TEMP_USERS)
await helper.mkdir(env.CDN_CARS)
await helper.mkdir(env.CDN_TEMP_CARS)
await helper.mkdir(env.CDN_LOCATIONS)
await helper.mkdir(env.CDN_TEMP_LOCATIONS)

export default app

First of all, we retrieve MongoDB connection string, then we establish a connection with the MongoDB database. Then we create an Express app and load middlewares such as cors, compression, helmet, and nocache. We set up various security measures using the helmet middleware library. we also import various route files for different parts of the application such as supplierRoutes, bookingRoutes, locationRoutes, notificationRoutes, carRoutes, and userRoutes. Finally, we load Express routes and export app.

There are 8 routes in the api. Each route has its own controller following the MVC design pattern and SOLID principles. Below are the main routes:

userRoutes: Provides REST functions related to users
supplierRoutes: Provides REST functions related to suppliers
countryRoutes: Provides REST functions related to countries
locationRoutes: Provides REST functions related to locations
carRoutes: Provides REST functions related to cars
bookingRoutes: Provides REST functions related to bookings
notificationRoutes: Provides REST functions related to notifications
stripeRoutes: Provides REST functions related to Stripe payment gateway

We are not going to explain each route one by one. We'll take, for example, countryRoutes and see how it was made:

import express from 'express'
import routeNames from '../config/countryRoutes.config'
import authJwt from '../middlewares/authJwt'
import * as countryController from '../controllers/countryController'

const routes = express.Router()

routes.route(routeNames.validate).post(authJwt.verifyToken, countryController.validate)
routes.route(routeNames.create).post(authJwt.verifyToken, countryController.create)
routes.route(routeNames.update).put(authJwt.verifyToken, countryController.update)
routes.route(routeNames.delete).delete(authJwt.verifyToken, countryController.deleteCountry)
routes.route(routeNames.getCountry).get(authJwt.verifyToken, countryController.getCountry)
routes.route(routeNames.getCountries).get(authJwt.verifyToken, countryController.getCountries)
routes.route(routeNames.getCountriesWithLocations).get(countryController.getCountriesWithLocations)
routes.route(routeNames.checkCountry).get(authJwt.verifyToken, countryController.checkCountry)
routes.route(routeNames.getCountryId).get(authJwt.verifyToken, countryController.getCountryId)

export default routes

First of all, we create an Express Router. Then, we create the routes using their name, method, middlewares and controllers.

routeNames contains countryRoutes route names:

const routes = {
  validate: '/api/validate-country',
  create: '/api/create-country',
  update: '/api/update-country/:id',
  delete: '/api/delete-country/:id',
  getCountry: '/api/country/:id/:language',
  getCountries: '/api/countries/:page/:size/:language',
  getCountriesWithLocations: '/api/countries-with-locations/:language/:imageRequired/:minLocations',
  checkCountry: '/api/check-country/:id',
  getCountryId: '/api/country-id/:name/:language',
}

export default routes

countryController contains the main business logic regarding countries. We are not going to see all the source code of the controller since it's quite large but we'll take create controller function for example.

Below is Country model:

import { Schema, model } from 'mongoose'
import * as env from '../config/env.config'

const countrySchema = new Schema<env.Country>(
  {
    values: {
      type: [Schema.Types.ObjectId],
      ref: 'LocationValue',
      required: [true, "can't be blank"],
      validate: (value: any): boolean => Array.isArray(value),
    },
  },
  {
    timestamps: true,
    strict: true,
    collection: 'Country',
  },
)

const Country = model<env.Country>('Country', countrySchema)

export default Country

Below is env.Country TypeScript type:

export interface Country extends Document {
  values: Types.ObjectId[]
  name?: string
}

A Country has multiple values. One per language. By default, English and French languages are supported.

Below is LocationValue model:

import { Schema, model } from 'mongoose'
import * as env from '../config/env.config'

const locationValueSchema = new Schema<env.LocationValue>(
  {
    language: {
      type: String,
      required: [true, "can't be blank"],
      index: true,
      trim: true,
      lowercase: true,
      minLength: 2,
      maxLength: 2,
    },
    value: {
      type: String,
      required: [true, "can't be blank"],
      index: true,
      trim: true,
    },
  },
  {
    timestamps: true,
    strict: true,
    collection: 'LocationValue',
  },
)

const LocationValue = model<env.LocationValue>('LocationValue', locationValueSchema)

export default LocationValue

Below is env.LocationValue TypeScript type:

export interface LocationValue extends Document {
  language: string
  value: string
}

A LocationValue has a language code (ISO 639-1) and a string value.

Below is create controller function:

export const create = async (req: Request, res: Response) => {
  const { body }: { body: bookcarsTypes.CountryName[] } = req
  const names = body

  try {
    const values: string[] = []
    for (const name of names) {
      const countryValue = new LocationValue({
        language: name.language,
        value: name.name,
      })
      await countryValue.save()
      values.push(countryValue.id)
    }

    const country = new Country({ values })
    await country.save()
    return res.send(country)
  } catch (err) {
    logger.error(`[country.create] ${i18n.t('DB_ERROR')} ${JSON.stringify(req.body)}`, err)
    return res.status(400).send(i18n.t('DB_ERROR') + err)
  }
}

In this function, we retrieve the body of the request, we iterate through the values provided in the body (one value per language) and we create a LocationValue. Finally, we create the country depending on the created location values.

Frontend

./frontend/src/assets/ folder contains CSS and images.
./frontend/src/pages/ folder contains React pages.
./frontend/src/components/ folder contains React components.
./frontend/src/services/ contains api client services.
./frontend/src/App.tsx is the main React App that contains routes.
./frontend/src/index.tsx is the main entry point of the frontend.

TypeScript type definitions are defined in the package ./packages/bookcars-types.

App.tsx is the main react App:

import React, { lazy, Suspense } from 'react'
import { BrowserRouter as Router, Route, Routes } from 'react-router-dom'
import env from '@/config/env.config'
import { GlobalProvider } from '@/context/GlobalContext'
import { init as initGA } from '@/common/ga4'

if (env.GOOGLE_ANALYTICS_ENABLED) {
  initGA()
}

const SignIn = lazy(() => import('@/pages/SignIn'))
const SignUp = lazy(() => import('@/pages/SignUp'))
const Activate = lazy(() => import('@/pages/Activate'))
const ForgotPassword = lazy(() => import('@/pages/ForgotPassword'))
const ResetPassword = lazy(() => import('@/pages/ResetPassword'))
const Home = lazy(() => import('@/pages/Home'))
const Search = lazy(() => import('@/pages/Search'))
const Checkout = lazy(() => import('@/pages/Checkout'))
const CheckoutSession = lazy(() => import('@/pages/CheckoutSession'))
const Bookings = lazy(() => import('@/pages/Bookings'))
const Booking = lazy(() => import('@/pages/Booking'))
const Settings = lazy(() => import('@/pages/Settings'))
const Notifications = lazy(() => import('@/pages/Notifications'))
const ToS = lazy(() => import('@/pages/ToS'))
const About = lazy(() => import('@/pages/About'))
const ChangePassword = lazy(() => import('@/pages/ChangePassword'))
const Contact = lazy(() => import('@/pages/Contact'))
const NoMatch = lazy(() => import('@/pages/NoMatch'))
const Locations = lazy(() => import('@/pages/Locations'))
const Suppliers = lazy(() => import('@/pages/Suppliers'))

const App = () => (
  <GlobalProvider>
    <Router>
      <div className="app">
        <Suspense fallback={<></>}>
          <Routes>
            <Route path="/sign-in" element={<SignIn />} />
            <Route path="/sign-up" element={<SignUp />} />
            <Route path="/activate" element={<Activate />} />
            <Route path="/forgot-password" element={<ForgotPassword />} />
            <Route path="/reset-password" element={<ResetPassword />} />
            <Route path="/" element={<Home />} />
            <Route path="/search" element={<Search />} />
            <Route path="/checkout" element={<Checkout />} />
            <Route path="/checkout-session/:sessionId" element={<CheckoutSession />} />
            <Route path="/bookings" element={<Bookings />} />
            <Route path="/booking" element={<Booking />} />
            <Route path="/settings" element={<Settings />} />
            <Route path="/notifications" element={<Notifications />} />
            <Route path="/change-password" element={<ChangePassword />} />
            <Route path="/about" element={<About />} />
            <Route path="/tos" element={<ToS />} />
            <Route path="/contact" element={<Contact />} />
            <Route path="/locations" element={<Locations />} />
            <Route path="/suppliers" element={<Suppliers />} />

            <Route path="*" element={<NoMatch />} />
          </Routes>
        </Suspense>
      </div>
    </Router>
  </GlobalProvider>
)

export default App

We are using React lazy loading to load each route.

We are not going to cover each page of the frontend, but you can open the source code and see each one if you want.

Mobile App

The customer receives push notifications if his booking is updated from the backend. Push notifications are built with Node.js, Expo Server SDK and Firebase.

./mobile/assets/ folder contains images.
./mobile/screens/ folder contains main React Native screens.
./mobile/components/ folder contains React Native components.
./mobile/services/ contains api client services.
./mobile/App.tsx is the main React Native App.

TypeScript type definitions are defined in:

./mobile/types/index.d.ts
./mobile/types/env.d.ts
./mobile/miscellaneous/bookcarsTypes.ts

./mobile/types/ is loaded in ./mobile/tsconfig.json as follow:

{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "strict": true,
    "typeRoots": [
      "./types"
    ]
  }
}

App.tsx is the main entry point of the React Native app:

import 'react-native-gesture-handler'
import React, { useCallback, useEffect, useRef, useState } from 'react'
import { RootSiblingParent } from 'react-native-root-siblings'
import { NavigationContainer, NavigationContainerRef } from '@react-navigation/native'
import { StatusBar as ExpoStatusBar } from 'expo-status-bar'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { Provider } from 'react-native-paper'
import * as SplashScreen from 'expo-splash-screen'
import * as Notifications from 'expo-notifications'
import { StripeProvider } from '@stripe/stripe-react-native'
import DrawerNavigator from './components/DrawerNavigator'
import * as helper from './common/helper'
import * as NotificationService from './services/NotificationService'
import * as UserService from './services/UserService'
import { GlobalProvider } from './context/GlobalContext'
import * as env from './config/env.config'

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: true,
    shouldSetBadge: true,
  }),
})

//
// Prevent native splash screen from autohiding before App component declaration
//
SplashScreen.preventAutoHideAsync()
  .then((result) => console.log(`SplashScreen.preventAutoHideAsync() succeeded: ${result}`))
  .catch(console.warn) // it's good to explicitly catch and inspect any error

const App = () => {
  const [appIsReady, setAppIsReady] = useState(false)

  const responseListener = useRef<Notifications.Subscription>()
  const navigationRef = useRef<NavigationContainerRef<StackParams>>(null)

  useEffect(() => {
    const register = async () => {
      const loggedIn = await UserService.loggedIn()
      if (loggedIn) {
        const currentUser = await UserService.getCurrentUser()
        if (currentUser?._id) {
          await helper.registerPushToken(currentUser._id)
        } else {
          helper.error()
        }
      }
    }

    //
    // Register push notifiations token
    //
    register()

    //
    // This listener is fired whenever a user taps on or interacts with a notification (works when app is foregrounded, backgrounded, or killed)
    //
    responseListener.current = Notifications.addNotificationResponseReceivedListener(async (response) => {
      try {
        if (navigationRef.current) {
          const { data } = response.notification.request.content

          if (data.booking) {
            if (data.user && data.notification) {
              await NotificationService.markAsRead(data.user, [data.notification])
            }
            navigationRef.current.navigate('Booking', { id: data.booking })
          } else {
            navigationRef.current.navigate('Notifications', {})
          }
        }
      } catch (err) {
        helper.error(err, false)
      }
    })

    return () => {
      Notifications.removeNotificationSubscription(responseListener.current!)
    }
  }, [])

  setTimeout(() => {
    setAppIsReady(true)
  }, 500)

  const onReady = useCallback(async () => {
    if (appIsReady) {
      //
      // This tells the splash screen to hide immediately! If we call this after
      // `setAppIsReady`, then we may see a blank screen while the app is
      // loading its initial state and rendering its first pixels. So instead,
      // we hide the splash screen once we know the root view has already
      // performed layout.
      //
      await SplashScreen.hideAsync()
    }
  }, [appIsReady])

  if (!appIsReady) {
    return null
  }

  return (
    <GlobalProvider>
      <SafeAreaProvider>
        <Provider>
          <StripeProvider publishableKey={env.STRIPE_PUBLISHABLE_KEY} merchantIdentifier={env.STRIPE_MERCHANT_IDENTIFIER}>
            <RootSiblingParent>
              <NavigationContainer ref={navigationRef} onReady={onReady}>
                <ExpoStatusBar style="light" backgroundColor="rgba(0, 0, 0, .9)" />
                <DrawerNavigator />
              </NavigationContainer>
            </RootSiblingParent>
          </StripeProvider>
        </Provider>
      </SafeAreaProvider>
    </GlobalProvider>
  )
}

export default App

We are not going to cover each screen of the mobile app, but you can open the source code and see each one if you want.

Admin Dashboard

./backend/assets/ folder contains CSS and images.
./backend/pages/ folder contains React pages.
./backend/components/ folder contains React components.
./backend/services/ contains api client services.
./backend/App.tsx is the main React App that contains routes.
./backend/index.tsx is the main entry point of the admin dashboard.

TypeScript type definitions are defined in the package ./packages/bookcars-types.

App.tsx of the backend follow similar logic like App.tsx of the frontend.

We are not going to cover each page of the admin dashboard but you can open the source code and see each one if you want.

Points of Interest

Building the mobile app with React Native and Expo is very easy. Expo makes mobile development with React Native very simple.

Using the same language (TypeScript) for backend, frontend and mobile development is very convenient.

That's it! I hope you enjoyed reading this article.

Resources

From Zero to Storefront: My Journey Building an E-commerce Site

aelassas — Thu, 07 Nov 2024 21:24:36 +0000

Introduction
Tech Stack
Quick Overview
API
Frontend
Admin Dashboard
Resources

Source code: https://github.com/aelassas/wexcommerce

Demo: https://wexcommerce.dynv6.net:8002

Introduction

For developers who value creative freedom and technical control, traditional eCommerce platforms like Shopify can feel restrictive. While Shopify's templates offer quick setup, and their Storefront API provides some flexibility, neither solution delivers the complete architectural freedom that modern developers crave.

The idea emerged from a desire to build without boundaries – a fully customizable eCommerce site where every aspect is within your control:

Own the UI/UX: Design unique customer experiences without fighting against template limitations
Control the Backend: Implement custom business logic and data structures that perfectly match the requirements
Master DevOps: Deploy, scale, and monitor the application with preferred tools and workflows
Extend Freely: Add new features and integrations without platform constraints or additional fees

Tech Stack

Here's the tech stack that made it possible:

Node.js
Next.js
MongoDB
MUI
TypeScript
Stripe
Docker

I chose Next.js for its powerful rendering capabilities, MongoDB for flexible data modeling, and Stripe for secure payment processing.

By choosing this stack, you're not just building a store – you're investing in a foundation that can evolve with your needs, backed by robust open-source technologies and a growing developer community.

Building a site with Next.js provides a solid foundation for scaling a business. Focus on performance, security, and user experience while maintaining code quality and documentation. Regular updates and monitoring will ensure the platform remains competitive and reliable.

Next.js stands out as an excellent choice due to its:

Superior Performance: Built-in optimizations for fast page loads and seamless user experiences
SEO Advantages: Server-side rendering capabilities that ensure your products are discoverable
Scalability: Enterprise-ready architecture that grows with your business
Rich Ecosystem: Vast collection of libraries and tools for rapid development
Developer Experience: Intuitive development workflow with hot reloading and automatic routing

Quick overview

Frontend

From the frontend, the user can search for available products, add products to cart and checkout.

Below is the landing page of the frontend:

Below is the search page of the frontend:

Below is a sample product page:

Below is a fullscreen view of product images:

Below is cart page:

Below is checkout page:

Below is the sign in page:

Below is the sign up page:

Below is the page where the user can see his orders:

That's it! Those are the main pages of the frontend.

Admin Dashboard

From the admin dashboard, admins can manage categories, products, users and orders.

Admins can also manage the following settings:

Locale Settings: Language of the platform (English or French) and currency
Delivery Settings: Delivery methods enabled and the cost of each one
Payment Settings: Payment methods enabled (Credit card, Cash on delivery or Wire transfer)
Bank Settings: Bank information for wire transfer (IBAN and other info)

Below is the sign in page:

Below is the dashboard page from which admins can see and manage orders:

Below is the page from which admins manage categories:

Below is the page from which admins can see and manage products:

Below is the page from which admins edit products:

Below is a fullscreen view of product images:

Below is settings page:

That's it. Those are the main pages of the admin dashboard.

API

The api is a Node.js server application that exposes a RESTful API using Express which gives access to MongoDB database.

The api is used by the frontend, the admin dashboard and will be used by the mobile app as well.

The api exposes all functions needed for the admin dashboard and the frontend. The api follows the MVC design pattern. JWT is used for authentication. There are some functions that need authentication such as functions related to managing products and orders, and others that do not need authentication such as retrieving categories and available products for non authenticated users:

./api/src/models/ folder contains MongoDB models.
./api/src/routes/ folder contains Express routes.
./api/src/controllers/ folder contains controllers.
./api/src/middlewares/ folder contains middlewares.
./api/src/app.ts is the main server where routes are loaded.
./api/src/index.ts is the main entry point of the api.

index.ts is in the main server:

import 'dotenv/config'
import process from 'node:process'
import fs from 'node:fs/promises'
import http from 'node:http'
import https, { ServerOptions } from 'node:https'
import * as env from './config/env.config'
import * as databaseHelper from './common/databaseHelper'
import app from './app'
import * as logger from './common/logger'

if (
  await databaseHelper.connect(env.DB_URI, env.DB_SSL, env.DB_DEBUG)
  && await databaseHelper.initialize()
) {
  let server: http.Server | https.Server

  if (env.HTTPS) {
    https.globalAgent.maxSockets = Number.POSITIVE_INFINITY
    const privateKey = await fs.readFile(env.PRIVATE_KEY, 'utf8')
    const certificate = await fs.readFile(env.CERTIFICATE, 'utf8')
    const credentials: ServerOptions = { key: privateKey, cert: certificate }
    server = https.createServer(credentials, app)

    server.listen(env.PORT, () => {
      logger.info('HTTPS server is running on Port', env.PORT)
    })
  } else {
    server = app.listen(env.PORT, () => {
      logger.info('HTTP server is running on Port', env.PORT)
    })
  }

  const close = () => {
    logger.info('Gracefully stopping...')
    server.close(async () => {
      logger.info(`HTTP${env.HTTPS ? 'S' : ''} server closed`)
      await databaseHelper.close(true)
      logger.info('MongoDB connection closed')
      process.exit(0)
    })
  }

  ['SIGINT', 'SIGTERM', 'SIGQUIT'].forEach((signal) => process.on(signal, close))
}

This is a TypeScript file that starts a server using Node.js and Express. It imports several modules including dotenv, process, fs, http, https, mongoose, and app. It then establishes a connection with MongoDB database. It then checks if the HTTPS environment variable is set to true, and if so, creates an HTTPS server using the https module and the provided private key and certificate. Otherwise, it creates an HTTP server using the http module. The server listens on the port specified in the PORT environment variable.

app.ts is the main entry point of the api:

import express from 'express'
import compression from 'compression'
import helmet from 'helmet'
import nocache from 'nocache'
import cookieParser from 'cookie-parser'
import i18n from './lang/i18n'
import * as env from './config/env.config'
import cors from './middlewares/cors'
import allowedMethods from './middlewares/allowedMethods'
import userRoutes from './routes/userRoutes'
import categoryRoutes from './routes/categoryRoutes'
import productRoutes from './routes/productRoutes'
import cartRoutes from './routes/cartRoutes'
import orderRoutes from './routes/orderRoutes'
import notificationRoutes from './routes/notificationRoutes'
import deliveryTypeRoutes from './routes/deliveryTypeRoutes'
import paymentTypeRoutes from './routes/paymentTypeRoutes'
import settingRoutes from './routes/settingRoutes'
import stripeRoutes from './routes/stripeRoutes'
import wishlistRoutes from './routes/wishlistRoutes'
import * as helper from './common/helper'

const app = express()

app.use(helmet.contentSecurityPolicy())
app.use(helmet.dnsPrefetchControl())
app.use(helmet.crossOriginEmbedderPolicy())
app.use(helmet.frameguard())
app.use(helmet.hidePoweredBy())
app.use(helmet.hsts())
app.use(helmet.ieNoOpen())
app.use(helmet.noSniff())
app.use(helmet.permittedCrossDomainPolicies())
app.use(helmet.referrerPolicy())
app.use(helmet.xssFilter())
app.use(helmet.originAgentCluster())
app.use(helmet.crossOriginResourcePolicy({ policy: 'cross-origin' }))
app.use(helmet.crossOriginOpenerPolicy())

app.use(nocache())
app.use(compression({ threshold: 0 }))
app.use(express.urlencoded({ limit: '50mb', extended: true }))
app.use(express.json({ limit: '50mb' }))

app.use(cors())
app.options('*', cors())
app.use(cookieParser(env.COOKIE_SECRET))
app.use(allowedMethods)

app.use('/', userRoutes)
app.use('/', categoryRoutes)
app.use('/', productRoutes)
app.use('/', cartRoutes)
app.use('/', orderRoutes)
app.use('/', notificationRoutes)
app.use('/', deliveryTypeRoutes)
app.use('/', paymentTypeRoutes)
app.use('/', settingRoutes)
app.use('/', stripeRoutes)
app.use('/', wishlistRoutes)

i18n.locale = env.DEFAULT_LANGUAGE

await helper.mkdir(env.CDN_USERS)
await helper.mkdir(env.CDN_TEMP_USERS)
await helper.mkdir(env.CDN_CATEGORIES)
await helper.mkdir(env.CDN_TEMP_CATEGORIES)
await helper.mkdir(env.CDN_PRODUCTS)
await helper.mkdir(env.CDN_TEMP_PRODUCTS)

export default app

First of all, we create an Express app and load middlewares such as cors, compression, helmet, and nocache. We set up various security measures using the helmet middleware library. We also import various route files for different parts of the application such as productRoutes, orderRoutes, categoryRoutes, notificationRoutes, userRoutes. Finally, we load Express routes and export app.

There are 11 routes in the api. Each route has its own controller following the MVC design pattern and SOLID principles. Below are the main routes:

userRoutes: Provides REST functions related to users
categoryRoutes: Provides REST functions related to categories
productRoutes: Provides REST functions related to products
cartRoutes: Provides REST functions related to carts
wishlistRoutes: Provides REST functions related to wishlists
deliveryTypeRoutes: Provides REST functions related to delivery methods
paymentTypeRoutes: Provides REST functions related to payment methods
orderRoutes: Provides REST functions related to orders
notificationRoutes: Provides REST functions related to notifications
settingRoutes: Provides REST functions related to settings
stripeRoutes: Provides REST functions related to Stripe payment gateway

We are not going to explain each route one by one. We'll take, for example, categoryRoutes and see how it was made:

import express from 'express'
import multer from 'multer'
import routeNames from '../config/categoryRoutes.config'
import authJwt from '../middlewares/authJwt'
import * as categoryController from '../controllers/categoryController'

const routes = express.Router()

routes.route(routeNames.validate).post(authJwt.verifyToken, categoryController.validate)
routes.route(routeNames.checkCategory).get(authJwt.verifyToken, categoryController.checkCategory)
routes.route(routeNames.create).post(authJwt.verifyToken, categoryController.create)
routes.route(routeNames.update).put(authJwt.verifyToken, categoryController.update)
routes.route(routeNames.delete).delete(authJwt.verifyToken, categoryController.deleteCategory)
routes.route(routeNames.getCategory).get(authJwt.verifyToken, categoryController.getCategory)
routes.route(routeNames.getCategories).get(categoryController.getCategories)
routes.route(routeNames.getFeaturedCategories).get(categoryController.getFeaturedCategories)
routes.route(routeNames.searchCategories).get(authJwt.verifyToken, categoryController.searchCategories)
routes.route(routeNames.createImage).post([authJwt.verifyToken, multer({ storage: multer.memoryStorage() }).single('image')], categoryController.createImage)
routes.route(routeNames.updateImage).post([authJwt.verifyToken, multer({ storage: multer.memoryStorage() }).single('image')], categoryController.updateImage)
routes.route(routeNames.deleteImage).post(authJwt.verifyToken, categoryController.deleteImage)
routes.route(routeNames.deleteTempImage).post(authJwt.verifyToken, categoryController.deleteTempImage)

export default routes

First of all, we create an Express Router. Then, we create routes using its name, its method, middlewares and its controller.

routeNames contains categoryRoutes route names:

export default {
    validate: '/api/validate-category',
    checkCategory: '/api/check-category/:id',
    create: '/api/create-category',
    update: '/api/update-category/:id',
    delete: '/api/delete-category/:id',
    getCategory: '/api/category/:id/:language',
    getCategories: '/api/categories/:language/:imageRequired',
    getFeaturedCategories: '/api/featured-categories/:language/:size',
    searchCategories: '/api/search-categories/:language',
    createImage: '/api/create-category-image',
    updateImage: '/api/update-category-image/:id',
    deleteImage: '/api/delete-category-image/:id',
    deleteTempImage: '/api/delete-temp-category-image/:image',
}

categoryController contains the main business logic regarding categories. We are not going to see all the source code of the controller since it's quite large but we'll take create controller function for example.

Below is Category model:

import { Schema, model } from 'mongoose'
import * as env from '../config/env.config'

const categorySchema = new Schema<env.Category>({
  values: {
    type: [Schema.Types.ObjectId],
    ref: 'Value',
    validate: (value: any) => Array.isArray(value),
  },
  image: {
    type: String,
  },
  featured: {
    type: Boolean,
    default: false,
  },
}, {
  timestamps: true,
  strict: true,
  collection: 'Category',
})

const Category = model<env.Category>('Category', categorySchema)

export default Category

A Category has multiple values. One value per language. By default, English and French languages are supported.

Below is Value model:

import { Schema, model } from 'mongoose'
import * as env from '../config/env.config'

const locationValueSchema = new Schema<env.Value>(
  {
    language: {
      type: String,
      required: [true, "can't be blank"],
      index: true,
      trim: true,
      lowercase: true,
      minLength: 2,
      maxLength: 2,
    },
    value: {
      type: String,
      required: [true, "can't be blank"],
      index: true,
      trim: true,
    },
  },
  {
    timestamps: true,
    strict: true,
    collection: 'Value',
  },
)

const Value = model<env.Value>('Value', locationValueSchema)

export default Value

A Value has a language code (ISO 639-1) and a string value.

Below is create controller function:

export const create = async (req: Request, res: Response) => {
  const { body }: { body: wexcommerceTypes.UpsertCategoryPayload } = req
  const { values, image, featured } = body

  try {
    if (image) {
      const _image = path.join(env.CDN_TEMP_CATEGORIES, image)

      if (!await helper.exists(_image)) {
        logger.error(i18n.t('CATEGORY_IMAGE_NOT_FOUND'), body)
        return res.status(400).send(i18n.t('CATEGORY_IMAGE_NOT_FOUND'))
      }
    }

    const _values = []
    for (const value of values) {
      const _value = new Value({
        language: value.language,
        value: value.value,
      })
      await _value.save()
      _values.push(_value._id)
    }

    const category = new Category({ values: _values, featured })
    await category.save()

    if (image) {
      const _image = path.join(env.CDN_TEMP_CATEGORIES, image)

      if (await helper.exists(_image)) {
        const filename = `${category._id}_${Date.now()}${path.extname(image)}`
        const newPath = path.join(env.CDN_CATEGORIES, filename)

        await fs.rename(_image, newPath)
        category.image = filename
        await category.save()
      }
    }

    return res.status(200).send(category)
  } catch (err) {
    logger.error(`[category.create] ${i18n.t('DB_ERROR')} ${req.body}`, err)
    return res.status(400).send(i18n.t('DB_ERROR') + err)
  }
}

In this function, we retrieve the body of the request, we iterate through the values provided in the body (one value per language) and we create a Value. Finally, we create the category depending on the created values and image file.

Frontend

The frontend is a web application built with Next.js and MUI. From the frontend, the user can search for available products, add them to cart and proceed to checkout depending on delivery and payment methods available.

./frontend/public/ folder contains public assets.
./frontend/src/styles/ folder contains CSS styles.
./frontend/src/components/ folder contains React components.
./frontend/src/lang/ contains locale files.
./frontend/src/app/ folder contains Next.js pages.
./frontend/src/lib/ contains server actions.
./frontend/next.config.ts is the main configuration file of the frontend.

The frontend was created with create-next-app:

npx create-next-app@latest

In Next.js, a page is a React Component exported from a .js, .jsx, .ts, or .tsx file in the pages directory. Each page is associated with a route based on its file name.

By default, Next.js pre-renders every page. This means that Next.js generates HTML for each page in advance, instead of having it all done by client-side JavaScript. Pre-rendering can result in better performance and SEO.

Each generated HTML is associated with minimal JavaScript code necessary for that page. When a page is loaded by the browser, its JavaScript code runs and makes the page fully interactive. (This process is called hydration.)

the frontend uses Server-Side Rendering for SEO optimization so that products can be indexed by search engines.

Admin Dashboard

The admin dashboard is a web application built with Next.js and MUI. From the admin dashboard, admins can manage categories, products, orders and users. When a new order is created, the admin user gets a notification and receives an email.

./backend/public/ folder contains public assets.
./backend/src/styles/ folder contains CSS styles.
./backend/src/components/ folder contains React components.
./backend/src/lang/ contains locale files.
./backend/src/app/ folder contains Next.js pages.
./backend/src/lib/ contains server actions.
./backend/next.config.ts is the main configuration file of the backend.

The admin dashboard was created with create-next-app too:

npx create-next-app@latest

Resources

That's it! I hope you enjoyed reading.

Test-Driven Development: A Comprehensive Guide

aelassas — Fri, 01 Nov 2024 09:59:59 +0000

Test-Driven Development (TDD) is a powerful approach that transforms how developers write code. Whether you're new to programming or looking to level up your skills, this guide will walk you through the essentials of TDD. You'll discover how writing tests before code can lead to more robust, maintainable software and boost your confidence as a developer. Let's explore the fundamentals together and set you on the path to becoming a test-driven practitioner.

Introduction
Development Environment
Prerequisites
Fake it!
Triangulation
Multiple Translations
Reverse Translation
File Loading
1. TranslatorDataSourceTest
2. TranslatorParserTest
3. TranslatorLoaderTest
Class Diagram
Test Results
Code Coverage
Running the Source Code
CI/CD
Is TDD a Time Waster?
Common Time-Related Misconceptions
Conclusion

You can find source code here: https://github.com/aelassas/tdd

Introduction

The traditional approach to writing unit tests involves writing tests to check the validity of your code. First, you begin by writing the code and then you write the tests. This is the opposite of test-driven development.

Test-driven development (TDD) involves writing tests before writing code, as shown in the workflow above.

First, the test is written and must fail at the beginning. Then, we write the code so that the test passes. Then, the test must be executed and must succeed. Then, the code is refactored. Then, the test must be performed again to ensure that the code is correct.

To summarize, this is done in five steps:

Write a test.
The test must fail at the beginning.
Write the code so that the test passes.
Execute the test and make sure it passes.
Refactor the code.

We can notice that in the workflow explained above, the tests are executed after the code has been refactored. This ensures that the code remains correct after refactoring.

This article will discuss TDD through a very simple example. The purpose of the example is to describe each step of TDD. The example will be developed in C# and the testing framework used is xUnit. We will be using Moq for mocking and dotCover for code coverage. We will be creating a multilingual translator through TDD. When writing code, we will try to respect SOLID principles and achieve 100% code coverage.

Development Environment

Visual Studio 2022
.NET 8.0

Prerequisites

C#
xUnit
Moq

Fake it!

The first task to achieve when using TDD is important: it must be so simple that the loop red-green-refactor can be completed quickly.

We first create a test class called TranslatorTest:

public class TranslatorTest
{
}

Then we will create the first unit test in this class, we initialize an object of type Translator with the name "en-fr" and we will check if the name is correct:

public class TranslatorTest
{
    [Fact]
    public void TestTranslatorName()
    {
        var translator = new Translator("en-fr");
        Assert.Equal("en-fr", translator.Name);
    }
}

The test will fail, which is what we want.

Now that we have reached the red bar, we will write some code so that the test passes. There are many ways to do this. We will use the "Fake it!" method. Specifically, it includes the minimum required to pass the test. In our case, it is enough to write a Translator class that returns the property Name of "en-fr":

public class Translator
{
    public string Name => "en-fr";
}

We will create the code step by step by using simple and quick methods in each step. Now, if we run our unit test again, it will pass. But the code is not refactored. There is a redundancy. Indeed, "en-fr" is repeated twice. We will refactor the code:

public class Translator(string name)
{
    public string Name => name;
}

After refactoring the code, we have to run the tests again to make sure the code is correct.

Code refactoring is a form of modifying code that preserves the execution of existing tests and obtains a software architecture with minimal defects. Some examples:

Remove duplicate code / move code.
Adjust private / public properties / methods.

We noticed that we have completed the cycle of TDD workflow. Now we can start the cycle over and over again with new tests.

Triangulation

In TDD, we write tests first, generating functional requirements before coding requirements. To refine the test, we will apply triangulation method.

Let's write a test that checks if a translation has been added to the translator (AddTranslation).

Testing will be done through GetTranslation method.

[Fact]
public void TestOneTranslation()
{
    var translator = new Translator("en-fr");
    translator.AddTranslation("against", "contre");
    Assert.Equal("contre", translator.GetTranslation("against"));
}

If we run the test, we'll notice that it fails. Okay, so that's what we're looking for at this step.

First, we'll use the "Fake it!" method to pass the test:

public class Translator(string name)
{
    public string Name => name;

    public void AddTranslation(string word, string translation)
    {
    }

    public string GetTranslation(string word) => "contre";
}

After running the test TestOneTranslation, we will notice that it passes.

But wait, there's code duplication. The keyword "contre" is repeated twice in the code. We will change the code to remove this duplication:

public class Translator(string name)
{
    private readonly Dictionary<string, string> _translations = new();
    public string Name => name;

    public void AddTranslation(string word, string translation)
    {
        _translations.Add(word, translation);
    }

    public string GetTranslation(string word) => _translations[word];
}

After refactoring the code, we have to run the tests again to make sure the code is correct.

Let's add a test to check if the translator is empty:

[Fact]
public void TestIsEmpty()
{
    var translator = new Translator("en-fr");
    Assert.True(translator.IsEmpty());
}

If we run the test, we'll notice that it fails. Okay, so that's what we're looking for at this step. Let's use the "Fake it!" method and write some code to pass the test:

public class Translator(string name)
{
    [...]

    public bool IsEmpty() => true;
}

If we run the test, we'll notice that it passes.

Now, let's use triangulation technique by using two assertions to drive the generalization of the code:

[Fact]
public void TestIsEmpty()
{
    var translator = new Translator("en-fr");
    Assert.True(translator.IsEmpty());
    translator.AddTranslation("against", "contre");
    Assert.False(translator.IsEmpty());
}

Now if we run the test again, It will fail because of the second assertion. This is called triangulation.

So let's fix this:

public class Translator(string name)
{
    [...]

    public bool IsEmpty() => _translations.Count == 0;
}

If we run the test again, we'll notice that it passes.

Multiple Translations

One feature of the translator is the ability to manipulate multiple translations. This use case was not initially planned in our architecture. Let’s write the test first:

[Fact]
public void TestMultipleTranslations()
{
    var translator = new Translator("en-fr");
    translator.AddTranslation("against", "contre");
    translator.AddTranslation("against", "versus");
    Assert.Equal<string[]>(["contre", "versus"], 
                 translator.GetMultipleTranslations("against"));
}

If we run the test, we'll notice that it fails. Okay, so that's what we're looking for at this step. First, we will use the "Fake it!" method to pass the test by modifying the method AddTranslation and adding the GetMultipleTranslations method:

public class Translator(string name)
{
    private readonly Dictionary<string, List<string>> _translations = new();
    public string Name => name;

    public string[] GetMultipleTranslation(string word) => ["contre", "versus"];

    [...]
}

After running the test TestMultipleTranslations, we will notice that it passes. But wait, there's code duplication. The string array ["contre", "versus"] is repeated twice in the code. We will change the code to remove this duplication:

public class Translator(string name)
{
    private readonly Dictionary<string, List<string>> _translations = new();
    public string Name => name;

    public void AddTranslation(string word, string translation)
    {
        if (_translations.TryGetValue(word, out var translations))
        {
            translations.Add(translation);
        }
        else
        {
            _translations.Add(word, [translation]);
        }
    }

    public string[] GetMultipleTranslation(string word) => [.. _translations[word]];

    public string GetTranslation(string word) => _translations[word][0];

    public bool IsEmpty() => _translations.Count == 0;
}

If we run the test again, we'll notice that it passes. Let's do some refactoring and rename GetMultipleTranslations to GetTranslation:

public class Translator(string name)
{
    private readonly Dictionary<string, List<string>> _translations = new();
    public string Name => name;

    public void AddTranslation(string word, string translation)
    {
        if (_translations.TryGetValue(word, out var translations))
        {
            translations.Add(translation);
        }
        else
        {
            _translations.Add(word, [translation]);
        }
    }

    public string[] GetTranslation(string word) => [.. _translations[word]];

    public bool IsEmpty() => _translations.Count == 0;
}

We also have to change our tests:

public class TranslatorTest
{
    [Fact]
    public void TestTranslatorName()
    {
        var translator = new Translator("en-fr");
        Assert.Equal("en-fr", translator.Name);
    }

    [Fact]
    public void TestIsEmpty()
    {
        var translator = new Translator("en-fr");
        Assert.True(translator.IsEmpty());
        translator.AddTranslation("against", "contre");
        Assert.False(translator.IsEmpty());
    }

    [Fact]
    public void TestOneTranslation()
    {
        var translator = new Translator("en-fr");
        translator.AddTranslation("against", "contre");
        Assert.Equal<string[]>(["contre"], translator.GetTranslation("against"));
    }

    [Fact]
    public void TestMultipleTranslations()
    {
        var translator = new Translator("en-fr");
        translator.AddTranslation("against", "contre");
        translator.AddTranslation("against", "versus");
        Assert.Equal<string[]>(["contre", "versus"], translator.GetTranslation("against"));
    }
}

Reverse Translation

Now suppose we want to consider translation in both directions, for example, a bilingual translator. Let's create the test first:

[Fact]
public void TestReverseTranslation()
{
    var translator = new Translator("en-fr");
    translator.AddTranslation("against", "contre");
    Assert.Equal<string[]>(["against"], translator.GetTranslation("contre"));
}

If we run the test, we'll notice that it fails. Okay, so that's what we're looking for at this step. Now, let's write the code to pass the test by using the "Fake it!" method:

public string[] GetTranslation(string word)
{
    if (_translations.TryGetValue(word, out var translations))
    {
        return [.. translations];
    }

    // Try reverse translation
    return ["against"];
}

The test will pass. But there is a code duplication. Indeed, "against" is repeated twice. So let's refactor the code:

public string[] GetTranslation(string word)
{
    if (_translations.TryGetValue(word, out var translations))
    {
        return [.. translations];
    }

    // Try reverse translation
    return [.. from t in _translations
               where t.Value.Contains(word)
               select t.Key];
}

If we run the test again, we'll notice that it passes.

File Loading

Now, let's handle loading translations from a data source (such as an external text file). Let's focus on external text files for now. The input format will be a text file where the first line contains the name of the translator and the other lines contain words separated by " = " . Here is an example:

en-fr
against = contre
against = versus

Here is the list of tests we will perform:

Empty file.
File containing only translator name.
File with translations.
Wrong file.

First, we'll use mocks to write tests. Then we'll write code along the way. Then we'll refactor the code. Finally, we'll test the code to make sure we refactored correctly and everything is working properly. We will create three new test classes:

TranslatorDataSourceTest: We will test a translator loaded from an external data source.
TranslatorParserTest: We will test the parsing of loaded translator data.
TranslatorLoaderTest: We will test the loading of translator data loaded from an external data source.

TranslatorDataSourceTest

Empty Translator Name

First, let's write the test:

[Fact]
public void TestEmptyTranslatorName()
{
    var mockTranslatorParser = new Mock<ITranslatorParser>();
    mockTranslatorParser
        .Setup(dp => dp.GetName())
        .Returns(string.Empty);

    var translator = new Translator(mockTranslatorParser.Object);
    Assert.Equal(string.Empty, translator.Name);
}

The test will fail. Okay, so that's what we're looking for at this step. We will use the interface ITranslatorParser to parse translator data loaded from external data source. Following is the interface ITranslatorParser:

public interface ITranslatorParser
{
    string GetName();
}

Let's modify the Translator class using the "Fake it!" method to pass the test:

public class Translator
{
    private readonly Dictionary<string, List<string>> _translations;
    public string Name { get; private set; }

    public Translator(string name)
    {
        _translations = [];
        Name = name;
    }

    public Translator(ITranslatorParser parser)
    {
        Name = string.Empty;
    }

    [...]
}

If we run the test again, we'll notice that it passes. But wait, there's a duplication in the code. Indeed, string.Empty is repeated twice. So, let's do some refactoring:

public class Translator
{
    private readonly Dictionary<string, List<string>> _translations;
    public string Name { get; private set; }

    public Translator(string name)
    {
        _translations = [];
        Name = name;
    }

    public Translator(ITranslatorParser parser)
    {
        Name = parser.GetName();
    }
}

If we run the test again, we'll notice that it passes.

No Translation

First, let's start by writing a test:

[Fact]
public void TestEmptyFile()
{
    var mockTranslatorParser = new Mock<ITranslatorParser>();
    mockTranslatorParser
        .Setup(dp => dp.GetTranslations())
        .Returns([]);

    var translator = new Translator(mockTranslatorParser.Object);
    Assert.Equal([], translator.GetTranslation("against"));
}

We will notice that the test will fail. Okay, so that's what we're looking for at this step. First, let's modify the interface ITranslatorParser:

public interface ITranslatorParser
{
    string GetName();
    Dictionary<string, List<string>> GetTranslations();
}

Then, let's write some code to pass the test using the "Fake it!" method:

public class Translator
{
    private readonly Dictionary<string, List<string>> _translations;
    public string Name { get; private set; }

    public Translator(string name)
    {
        _translations = [];
        Name = name;
    }

    public Translator(ITranslatorParser parser)
    {
        _translations = [];
        Name = parser.GetName();
    }

    [...]
}

If we run the test again, we'll notice that it passes. But wait, there's a duplication in the code. In fact, the translator initialization is repeated twice. So, let's do some refactoring:

public class Translator
{
    private readonly Dictionary<string, List<string>> _translations;
    public string Name { get; private set; }

    public Translator(string name)
    {
        _translations = [];
        Name = name;
    }

    public Translator(ITranslatorParser parser)
    {
        _translations = parser.GetTranslations();
        Name = parser.GetName();
    }

  [...]
}

If we run the test again, we'll notice that it passes.

File with only Translator Name

First, let's start by writing a test:

[Fact]
public void TestTranslatorName()
{
    var mockTranslatorParser = new Mock<ITranslatorParser>();
    mockTranslatorParser
        .Setup(dp => dp.GetName())
        .Returns("en-fr");

    var translator = new Translator(mockTranslatorParser.Object);
    Assert.Equal("en-fr", translator.Name);
}

We will notice that the test will pass because we have written the interface ITranslatorParser and changed the Translator class. Currently, this unit does not require refactoring.

One Translation

First, let's start by writing a test:

[Fact]
public void TestOneTranslation()
{
    var mockTranslatorParser = new Mock<ITranslatorParser>();
    mockTranslatorParser
        .Setup(dp => dp.GetTranslations())
        .Returns(new Dictionary<string, List<string>>
        {
                {"against", ["contre"] }
        });

    var translator = new Translator(mockTranslatorParser.Object);
    Assert.Equal<string[]>(["contre"], translator.GetTranslation("against"));
}

We will notice that the test will pass because we have written the interface ITranslatorParser and changed the Translator class. Currently, this unit does not require refactoring.

Multiple Translations

First, let's start by writing a test:

[Fact]
public void TestMultipleTranslations()
{
    var mockTranslatorParser = new Mock<ITranslatorParser>();
    mockTranslatorParser
        .Setup(dp => dp.GetTranslations())
        .Returns(new Dictionary<string, List<string>>
        {
            { "against", ["contre", "versus"]}
        });

    var translator = new Translator(mockTranslatorParser.Object);
    Assert.Equal<string[]>(["contre", "versus"], translator.GetTranslation("against"));
}

We will notice that the test will pass because we have written the interface ITranslatorParser and changed the Translator class. Currently, this unit does not require refactoring.

Wrong File

First, let's start by writing a test:

[Fact]
public void TestErroneousFile()
{
    var mockTranslatorParser = new Mock<ITranslatorParser>();
    mockTranslatorParser
        .Setup(dp => dp.GetTranslations())
        .Throws(new TranslatorException("The file is erroneous."));

    Assert.Throws<TranslatorException>(() => new Translator(mockTranslatorParser.Object));
}

We will notice that the test will pass because we have written the interface ITranslatorParser and changed the Translator class. Currently, this unit does not require refactoring.

TranslatorParserTest

Now let's create a class to parse loaded translator data through ITranslatorLoader, which loads translator data from external data source.

Empty Translator Name

First, let's start by writing a test:

[Fact]
public void TestEmptyTranslatorName()
{
    var mockTranslatorLoader = new Mock<ITranslatorLoader>();
    mockTranslatorLoader
        .Setup(dl => dl.GetLines())
        .Returns([]);

    var translatorParser = new TranslatorParser(mockTranslatorLoader.Object);
    Assert.Equal(string.Empty, translatorParser.GetName());
}

The test will fail. Okay, so that's what we're looking for at this step. We will use an interface ITranslatorLoader to load translator data from an external data source. The following is the interface ITranslatorLoader:

public interface ITranslatorLoader
{
    string[] GetLines();
}

Let's write some code to pass the test using the "Fake it!" method:

public class TranslatorParser(ITranslatorLoader loader) : ITranslatorParser
{
    public string GetName() => string.Empty;
    public Dictionary<string, List<string>> GetTranslations() => new();
}

The test will pass. Let's move on to other units.

No Translation

Let's start by writing a test:

[Fact]
public void TestNoTranslation()
{
    var mockTranslatorLoader = new Mock<ITranslatorLoader>();
    mockTranslatorLoader
        .Setup(dl => dl.GetLines())
        .Returns([]);

    var translatorParser = new TranslatorParser(mockTranslatorLoader.Object);
    Assert.Equal([], translatorParser.GetTranslations());
}

The test will pass. Let's move on to other units.

Translator Name

Let's start by writing a test:

[Fact]
public void TestTranslatorName()
{
    var mockTranslatorLoader = new Mock<ITranslatorLoader>();
    mockTranslatorLoader
        .Setup(dl => dl.GetLines())
        .Returns(["en-fr"]);

    var translatorParser = new TranslatorParser(mockTranslatorLoader.Object);
    Assert.Equal("en-fr", translatorParser.GetName());
}

The test will fail. Okay, so that's what we're looking for in this step. Let's write some code to pass the test using the "Fake it!" method:

public class TranslatorParser(ITranslatorLoader loader) : ITranslatorParser
{
    public string GetName() => "en-fr";
    public Dictionary<string, List<string>> GetTranslations() => new();
}

The test will pass. But wait, there is a duplication in the code and the test TestEmptyTranslatorName fails. So let's solve this issue:

public class TranslatorParser(ITranslatorLoader loader) : ITranslatorParser
{
    private readonly string[] _lines = loader.GetLines();

    public string GetName() => _lines.Length > 0 ? _lines[0] : string.Empty;
    public Dictionary<string, List<string>> GetTranslations() => new();
}

Now, the test will pass.

One Translation

Let's start by writing a test:

[Fact]
public void TestOneTranslation()
{
    var mockTranslatorLoader = new Mock<ITranslatorLoader>();
    mockTranslatorLoader
        .Setup(dl => dl.GetLines())
        .Returns(["en-fr", "against = contre"]);

    var translatorParser = new TranslatorParser(mockTranslatorLoader.Object);
    var expected = new Dictionary<string, List<string>>
    {
        {"against", ["contre"]}
    };
    Assert.Equal(expected, translatorParser.GetTranslations());
}

The test will fail. Okay, so that's what we're looking for at this step. Let's write some code to pass the test using the "Fake it!" method:

public class TranslatorParser(ITranslatorLoader loader) : ITranslatorParser
{
    private readonly string[] _lines = loader.GetLines();

    public string GetName() => _lines.Length > 0 ? _lines[0] : string.Empty;
    public Dictionary<string, List<string>> GetTranslations() => new()
    {
        {"against", ["contre"]}
    };
}

The test will pass. But wait, there is a duplication in the code and the test TestNoTranslation fails. So let's fix this:

public partial class TranslatorParser(ITranslatorLoader loader) : ITranslatorParser
{
    private static readonly Regex TranslatorRegex = new(@"^(?<key>\w+) = (?<value>\w+)$");

    private readonly string[] _lines = loader.GetLines();

    public string GetName() => _lines.Length > 0 ? _lines[0] : string.Empty;

    public Dictionary<string, List<string>> GetTranslations()
    {
        var translator = new Dictionary<string, List<string>>();

        if (_lines.Length <= 1)
        {
            return translator;
        }

        for (var i = 1; i < _lines.Length; i++)
        {
            var line = _lines[i];
            var match = TranslatorRegex.Match(line);

            var key = match.Groups["key"].Value;
            var value = match.Groups["value"].Value;

            if (translator.TryGetValue(key, out var translations))
            {
                translations.Add(value);
            }
            else
            {
                translator.Add(key, [value]);
            }
        }

        return translator;
    }
}

Now the test will pass. The method GetTranslations just parses the lines loaded by ITranslatorLoader.

Multiple Translations

Let's start by writing a test:

[Fact]
public void TestMultipleTranslations()
{
    var mockTranslatorLoader = new Mock<ITranslatorLoader>();
    mockTranslatorLoader
        .Setup(dl => dl.GetLines())
        .Returns(["en-fr", "against = contre", "against = versus"]);

    var translatorParser = new TranslatorParser(mockTranslatorLoader.Object);
    var expected = new Dictionary<string, List<string>>
    {
        {"against", ["contre", "versus"]}
    };
    Assert.Equal(expected, translatorParser.GetTranslations());
}

We will notice that the test will pass because we implemented TranslatorParser. Currently, this unit does not require refactoring.

Wrong File

One of the features we haven't implemented yet is handling the loading of wrong files. This use case was not initially planned in our architecture. Let's write the test first:

[Fact]
public void TestErroneousFile()
{
    var mockTranslatorLoader = new Mock<ITranslatorLoader>();
    mockTranslatorLoader
        .Setup(dl => dl.GetLines())
        .Returns(["en-fr", "against = ", "against = "]);

    var translatorParser = new TranslatorParser(mockTranslatorLoader.Object);
    Assert.Throws<TranslatorException>(translatorParser.GetTranslations);
}

The test will fail. Okay, so that's what we're looking for at this step. Let's update the code to pass the test:

public partial class TranslatorParser(ITranslatorLoader loader) : ITranslatorParser
{
    private static readonly Regex TranslatorRegex = new(@"^(?<key>\w+) = (?<value>\w+)$");

    private readonly string[] _lines = loader.GetLines();

    public string GetName() => _lines.Length > 0 ? _lines[0] : string.Empty;

    public Dictionary<string, List<string>> GetTranslations()
    {
        var translator = new Dictionary<string, List<string>>();

        if (_lines.Length <= 1)
        {
            return translator;
        }

        for (var i = 1; i < _lines.Length; i++)
        {
            var line = _lines[i];
            var match = TranslatorRegex.Match(line);

            if (!match.Success)
            {
                throw new TranslatorException("The file is erroneous.");
            }

            var key = match.Groups["key"].Value;
            var value = match.Groups["value"].Value;

            if (translator.TryGetValue(key, out var translations))
            {
                translations.Add(value);
            }
            else
            {
                translator.Add(key, [value]);
            }
        }

        return translator;
    }
}

Now, we'll notice that the test will pass because we handled the case of wrong files by throwing TranslatorException in case of a wrong line.

TranslatorLoaderTest

Now, we will create a class that loads translator data from an external file.

Empty File

Let's start with the first test that tests an empty file:

[Fact]
public void TestEmptyFile()
{
    var translatorLoader = new TranslatorLoader(@"..\..\..\..\..\data\translator-empty.txt");
    Assert.Equal([], translatorLoader.GetLines());
}

The test will fail. Okay, so that's what we're looking for at this step. Now, let's write some code to pass the test using the "Fake it!" method:

public class TranslatorLoader(string path) : ITranslatorLoader
{
    public string[] GetLines() => [];
}

Now the test will pass. But wait, there's code duplication. In fact, The empty string array is repeated twice in the code. So, let's do some refactoring:

public class TranslatorLoader(string path) : ITranslatorLoader
{
    public string[] GetLines() => File.ReadAllLines(path);
}

Now, if we run the test again, we'll see that it passes.

Files with only Translator Names

Now, let's use the following text file (translator-name.txt):

en-fr

Let's start by writing the test:

[Fact]
public void TestTranslatorName()
{
    var translatorLoader = new TranslatorLoader(@"..\..\..\..\..\data\translator-name.txt");
    Assert.Equal<string[]>(["en-fr"], translatorLoader.GetLines());
}

The test will pass because we implemented the class TranslatorLoader in the previous test. Let's move on to other units.

Files with Translations

Now, let's use the following translator file (translator.txt):

en-fr
against = contre
against = versus

Let's start by writing the test:

[Fact]
public void TestMultipleTranslations()
{
    var translatorLoader = new TranslatorLoader(@"..\..\..\..\..\data\translator.txt");
    Assert.Equal<string[]>(["en-fr", "against = contre", "against = versus"], translatorLoader.GetLines());
}

Again, the test will pass because we implemented the TranslatorLoader class in previous tests.

Wrong File

Now, let's use the following translator file (translator-erroneous.txt):

en-fr
against = 
against =

Let's write the test first:

[Fact]
public void TestErroneousFile()
{
    var translatorLoader = new TranslatorLoader(@"..\..\..\..\..\data\translator-erroneous.txt");
    Assert.Equal<string[]>(["en-fr", "against = ", "against = "], translatorLoader.GetLines());
}

Again, the test will pass because we implemented the TranslatorLoader class in previous tests. We completed the testing and created the TranslatorLoader class responsible for loading translator data from an external file.

Class Diagram

We have finished coding our multilingual translator through TDD.

The following is the class diagram:

Test Results

If we run all the tests, we'll notice that they all pass:

You can find test results on GitHub Actions.

Code Coverage

Here is the code coverage:

We'll notice that we've reached 100% code coverage. This is one of the advantages of TDD.

You can find code coverage report on Codecov.

Running the Source Code

To run the source code, do the following:

Download the source code.
Open tdd.sln in Visual Studio 2022.
Run all the tests in the solution.
To get code coverage, you can use dotCover.

CI/CD

Test-Driven Development (TDD) and code coverage play significant roles in enhancing Continuous Integration/Continuous Deployment (CI/CD) practices. Here's how they influence the process:

TDD (Test-Driven Development)

Improved Code Quality: TDD emphasizes writing tests before code, which leads to better-designed, more maintainable code. This ensures that the code meets requirements from the start, reducing bugs in later stages.
Faster Feedback Loop: With TDD, developers receive immediate feedback on their code. When integrated into a CI/CD pipeline, this rapid feedback helps catch issues early, allowing for quicker iterations and deployments.
Reduced Debugging Time: Since tests are written alongside code, developers can identify and fix bugs early in the development process, minimizing the time spent on debugging later.

Code Coverage

Measurement of Test Effectiveness: Code coverage tools analyze how much of the codebase is tested by unit tests. High coverage indicates that most of the code is exercised by tests, providing confidence that changes won’t introduce new bugs.
Guiding Refactoring: With insights from code coverage reports, developers can identify untested or poorly tested areas of the code. This can guide efforts to improve code quality and test completeness.
Enhanced CI/CD Confidence: High code coverage and comprehensive test suites increase confidence in deploying changes. CI/CD pipelines can be designed to fail deployments if coverage drops below a certain threshold, ensuring that quality is maintained.

Overall Influence

Streamlined Development: TDD and code coverage promote a culture of quality and accountability, leading to smoother CI/CD processes where developers feel confident pushing changes.
Risk Mitigation: By ensuring that changes are well-tested and documented through TDD and monitoring code coverage, teams can significantly reduce the risks associated with deployment.

In summary, TDD and code coverage are integral to building robust CI/CD pipelines, fostering a culture of quality and continuous improvement in software development.

Build Workflow

Here is the build workflow of our project:

name:  build

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-dotnet@v3
        with:
            dotnet-version: 8.x
      - name: Build
        run: dotnet build

Let's break down what this workflow does:

Trigger Conditions:

Activates when someone pushes directly to the main branch
Activates when someone opens/updates a pull request targeting main

Environment:

Uses a Windows environment (windows-latest)
Good for .NET projects which are often Windows-based

Steps in Order:

Checks out the code using checkout@v3
Installs .NET 8.x using setup-dotnet@v3
Runs the build command using dotnet build

Test Worfklow

Here is the test workflow of our project:

name: test

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-dotnet@v3
        with:
            dotnet-version: 8.x
      - name: Test
        run: dotnet test --verbosity normal /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura
      - name: Upload coverage reports to Codecov
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          file: coverage.cobertura.xml
          directory: ./tests/Translator.UnitTests

Let's break down what this workflow does:

Test Execution:

Runs tests with detailed output (--verbosity normal)
Collects code coverage using Coverlet
Generates report in Cobertura format (widely supported)

Coverage Integration:

Uses Codecov for coverage tracking
Requires a CODECOV_TOKEN secret in repository
Specifies the test directory path

Is TDD a Time Waster?

The short answer is no - but the reality deserves a thoughtful discussion.

While TDD requires upfront time investment in writing tests before code, it typically saves significant time in the long run through:

Reduced Debugging Time

Tests catch bugs immediately rather than during later testing phases
Problems are easier to fix when the related code is fresh in your mind
Fewer issues make it to production, saving emergency debugging sessions

Improved Code Quality

Writing tests first forces better design decisions
Code is naturally more modular and maintainable
Refactoring becomes safer and faster with test coverage

Documentation Benefits

Tests serve as living documentation of how code should behave
New team members can understand expectations by reading tests
Less time spent writing and maintaining separate documentation

Faster Development Cycles

While initial development might feel slower, overall delivery speeds up
Less time spent on bug fixes and rework
More confident and rapid deployments

Common Time-Related Misconceptions

"Writing tests doubles development time" - Actually, TDD often reduces total development time when accounting for debugging and maintenance
"TDD slows down prototyping" - You can adjust test coverage based on project phase
"Tests take too long to maintain" - Well-written tests require less maintenance than fixing recurring bugs

The key is viewing TDD as an investment rather than overhead. Like any skill, it takes time to master, but the returns in code quality, developer confidence, and long-term maintenance costs make it worthwhile for most projects.

Conclusion

Our journey with TDD has yielded remarkable results that extend far beyond just testing. By embracing this methodology, we've created code that stands on a solid foundation. The comprehensive unit test suite and 100% code coverage provide a safety net that catches issues early and enables confident refactoring. But TDD's benefits reach deeper into the very architecture of our code – it naturally guides us toward SOLID principles, producing solutions that are maintainable, flexible, and extensible.

Perhaps most importantly, our codebase tells a clear story. Each test serves as documentation, making the intended behavior crystal clear to anyone working with the code. The reduced debugging time is a welcome bonus, but the real victory lies in how TDD has helped us craft more coherent, well-structured software that's built to evolve with our needs.

As we've seen, TDD isn't just about testing – it's about building better software from the ground up.

Test-Driven Development shines brightest in environments where code evolves continuously. By breaking down software into small, testable units, TDD empowers developers to make changes with confidence. This approach not only ensures code quality but fundamentally shifts how we think about software design. Rather than viewing applications as monolithic structures, TDD encourages a modular mindset where components are crafted independently, thoroughly tested, and seamlessly integrated. As you begin your TDD journey, remember that you're not just learning a testing methodology – you're adopting a development philosophy that will help you build more maintainable, reliable, and scalable software.

That's it! I hope you enjoyed reading.

Functional Programming in TypeScript

aelassas — Mon, 28 Oct 2024 07:51:16 +0000

Introduction
TypeScript Environment
Representing Data Through Functions
1. Sets
2. Binary Operations
3. Go Further
Euclidean Plane
1. Drawing a Disk
2. Drawing Horizontal and Vertical Half-planes
3. Functions
4. Go Further
Fractals
1. Complex Numbers and Drawing
2. Mandelbrot Fractal
3. Go Further
Unit Tests

Source code: https://github.com/aelassas/functional-ts

Introduction

In TypeScript, functions are nothing but objects. Hence, functions can be constructed, passed as parameter, returned from functions or assigned into variables. Thus, TypeScript has first-class functions. More precisely, TypeScript supports the following:

Higher-order functions arguments
Higher-order functions results
Nested functions
Anonymous functions
Closures
Partial application (ECMAScript 5)

This article will not discuss the basics of functional programming, as you can find numerous resources on this topic. Instead, it will talk about functional programming in TypeScript applied to algebra, numbers, Euclidean plane, and fractals. The examples provided in this article will start from simple to more complex but always illustrated in a simple, straightforward and easy-to-understand manner.

TypeScript Environment

To run the source code, you'll need to install Node.js. Once Node.js is installed, clone the GitHub repository:

git clone https://github.com/aelassas/functional-ts.git

Go to the source code folder, set up TypeScript environment and install all necessary dependencies with the following commands:

cd functional-ts
npm install

To run numbers demo, run the following command:

npm run numbers

To run Euclidean plane demo, run the following command:

npm run plane

To run fractals demo, run the following command:

npm run fractals

To run unit tests, run the following command:

npm test

Representing Data Through Functions

Let S be any set of elements a, b, c ... (for instance, the books on the table or the points of the Euclidean plane) and let S' be any subset of these elements (for instance, the green books on the table or the points in the circle of radius 1 centered at the origin of the Euclidean plane).

The Characteristic Function S'(x) of the set S' is a function which associates either true or false with each element x of S.

S'(x) = true if x is in S'
S'(x) = false if x is not in S'

Let S be the set of books on the table and let S' be the set of green books on the table. Let a and b be two green books, and let c and d be two red books on the table. Then:

S'(a) = S'(b) = true
S'(c) = S'(d) = false

Let S be the set of the points in the Euclidean plane and let S' be the set of the points in the circle of radius 1 centered at the origin of the Euclidean plane (0, 0) (unit circle). Let a and b be two points in the unit circle, and let c and d be two points in a circle of radius 2 centered at the origin of the Euclidean plane. Then:

S'(a) = S'(b) = true
S'(c) = S'(d) = false

type Set<T> = (x: T) => boolean

In the next sections, we will see how to represent some fundamental sets in the algebra of sets through TypeScript in a functional way, then we will define generic binary operations on sets. We will then apply these operations on numbers then on subsets of the Euclidean plane. Sets are abstract data structures, the subsets of numbers and the subsets of the Euclidean plane are the representation of abstract data-structures, and finally the binary operations are the generic logics that works on any representation of the abstract data structures.

Sets

This section introduces the representation of some fundamental sets in the algebra of sets through TypeScript.

Empty set

Let E be the empty set and Empty its Characteristic function. In algebra of sets, E is the unique set having no elements. Therefore, Empty can be defined as follows:

Empty(x) = false if x is in E
Empty(x) = false if x is not in E

Thus, the representation of E in TypeScript can be defined as follows:

const empty = <T>() => (e: T) => false

In algebra of sets, Empty is represented as follows:

Thus, running the code below:

console.log('\nEmpty set:')
console.log('Is 7 in {}?', common.empty<number>()(7))

gives the following results:

Set All

All(x) = true if x is in S

Thus, the representation of S' in TypeScript can be defined as follows:

const all = <T>() => (e: T) => true

In algebra of sets, All is represented as follows:

Thus, running the code below:

console.log('\nSet All:')
console.log('Is 7 in integers set?', common.all<number>()(7))

gives the following results:

Singleton Set

Singleton(x) = true if x is e
Singleton(x) = false if x is not e

Thus, the representation of E in TypeScript can be defined as follows:

const singleton = <T>(x: T) => (y: T) => x === y

Thus, running the code below:

console.log('\nSingleton set:')
console.log('Is 7 in the singleton set {0}?', common.singleton(0)(7))
console.log('Is 7 in the singleton set {7}?', common.singleton(7)(7)

gives the following results:

Other Sets

This section presents subsets of the integers set.

Even Numbers

Let E be the set of even numbers and Even its Characteristic function. In mathematics, an even number is a number which is a multiple of two. Therefore, Even can be defined as follows:

Even(x) = true if x is a multiple of 2
Even(x) = false if x is not a multiple of 2

Thus, the representation of E in TypeScript can be defined as follows:

const even = (x: number) => x % 2 === 0

Thus, running the code below:

console.log('\nEven numbers set:')
console.log('Is 99 in even numbers set?', numbers.even(99))
console.log('Is 998 in even numbers set?', numbers.even(998))

gives the following results:

Odd Numbers

Let E be the set of odd numbers and Odd its Characteristic function. In mathematics, an odd number is a number which is not a multiple of two. Therefore, Odd can be defined as follows:

Odd(x) = true if x is not a multiple of 2
Odd(x) = false if x is a multiple of 2

Thus, the representation of E in TypeScript can be defined as follows:

const odd = (x: number) => x % 2 === 1

Thus, running the code below:

console.log('\nOdd numbers set:')
console.log('Is 99 in odd numbers set?', numbers.odd(99))
console.log('Is 998 in odd numbers set?', numbers.odd(998))

gives the following results:

Multiples of 3

MultipleOfThree(x) = true if x is divisible by 3
MultipleOfThree(x) = false if x is not divisible by 3

Thus, the representation of E in TypeScript can be defined as follows:

jsconst multipleOfThree = (x: number) => x % 3 === 0

Thus, running the code below:

console.log('\nMultiples of 3 set:')
console.log('Is 99 in multiples of 3 set?', numbers.multipleOfThree(99))
console.log('Is 998 in multiples of 3 set?', numbers.multipleOfThree(998))

gives the following results:

Multiples of 5

MultipleOfFive(x) = true if x is divisible by 5
MultipleOfFive(x) = false if x is not divisible by 5

Thus, the representation of E in TypeScript can be defined as follows:

jsconst multipleOfFive = (x: number) => x % 5 === 0

Thus, running the code below:

console.log('\nMultiples of 5 set:')
console.log('Is 15 in multiples of 5 set?', numbers.multipleOfFive(15))
console.log('Is 998 in multiples of 5 set?', numbers.multipleOfFive(998))

gives the following results:

Prime Numbers

A long time ago, when I was playing with Project Euler problems, I had to resolve the following one:

By listing the first six prime numbers: 2, 3, 5, 7, 11, and 13, 
we can see that the 6th prime is 13.
What is the 10 001st prime number?

To resolve this problem, I first had to write a fast algorithm that checks whether a given number is prime or not. Once the algorithm written, I wrote an iterative algorithm that iterates through primes until the 10 001st prime number was found.

Prime(x) = true if x is prime
Prime(x) = false if x is not prime

Thus, the representation of E in TypeScript can be defined as follows:

const prime = (x: number) => {
  if (x <= 1) return false
  if (x < 4) return true
  if (x % 2 === 0) return false
  if (x < 9) return true
  if (x % 3 === 0) return false
  const sqrt = Math.sqrt(x)
  for (let i = 5; i <= sqrt; i += 6) {
    if (x % i === 0) return false
    if (x % (i + 2) === 0) return false
  }
  return true
}

Thus, running the code below to resolve our problem:

console.log('\nPrimes set:')
console.log('Is 2 in primes set?', numbers.prime(2))
console.log('Is 4 in primes set?', numbers.prime(4))
console.log('The 10 001st prime number is', numbers.getPrime(10001))

where getPrime is defined below:

const getPrime = (p: number) => {
  for (let i = 1, count = 0; ; i++) {
    if (prime(i)) count++
    if (count === p) return i
  }
}

gives the following results:

Binary Operations

This section presents several fundamental operations for constructing new sets from given sets and for manipulating sets. Below the Ven diagram in the algebra of sets.

Union

Let E and F be two sets. The union of E and F, denoted by E U F is the set of all elements which are members of either E and F.

Let Union be the union operation. Thus, the Union operation can be implemented as follows in TypeScript:

const union = <T>(e: Set<T>, f: Set<T>) => (x: T) => e(x) || f(x)

Running the code below:

console.log('\nUnion:')
console.log('Is 7 in the union of Even and Odd Integers Set?', core.union(numbers.even, numbers.odd)(7))

gives the following results:

Intersection

Let E and F be two sets. The intersection of E and F, denoted by E n F is the set of all elements which are members of both E and F.

Let Intersection be the intersection operation. Thus, the Intersection operation can be implemented as follows in TypeScript:

jsconst intersection = <T>(e: Set<T>, f: Set<T>) => (x: T) => e(x) && f(x)

Running the code below:

console.log('\nIntersection:')
const multiplesOfThreeAndFive = core.intersection(numbers.multipleOfThree, numbers.multipleOfFive)
console.log('Is 15 a multiple of 3 and 5?', multiplesOfThreeAndFive(15))
console.log('Is 10 a multiple of 3 and 5?', multiplesOfThreeAndFive(10))

gives the following results:

Cartesian Product

Let E and F be two sets. The cartesian product of E and F, denoted by E × F is the set of all ordered pairs (e, f) such that e is a member of E and f is a member of F.

Let CartesianProduct be the cartesian product operation. Thus, the CartesianProduct operation can be implemented as follows in TypeScript:

const cartesianProduct = <T1, T2>(e: Set<T1>, f: Set<T2>) => (x: T1, y: T2) => e(x) && f(y)

Running the code below:

console.log('\nCartesian Product:')
const cp = core.cartesianProduct(numbers.multipleOfThree, numbers.multipleOfFive)
console.log('Is (9, 15) in MultipleOfThree x MultipleOfFive? ', cp(9, 15))

gives the following results:

Complements

Let E and F be two sets. The relative complement of F in E, denoted by E \ F is the set of all elements which are members of E but not members of F.

Let Complement be the relative complement operation. Thus, the Complement operation can be implemented as follows in TypeScript:

const complement = <T>(e: Set<T>, f: Set<T>) => (x: T) => e(x) && !f(x)```



Running the code below:



```js
console.log('\nComplement:')
const c = core.complement(numbers.multipleOfThree, numbers.multipleOfFive)
console.log('Is 15 in MultipleOfThree \\ MultipleOfFive set? ', c(15))
console.log('Is 9 in MultipleOfThree \\ MultipleOfFive set? ', c(9))

gives the following results:

Symmetric Difference

Let SymmetricDifference be the symmetric difference operation. Thus, the SymmetricDifference operation can be implemented in two ways in TypeScript. A trivial way is to use the union and complement operations as follows:

const symmetricDifferenceWithoutXor = <T>(e: Set<T>, f: Set<T>) => 
      (x: T) => union(complement<T>(e, f), complement(f, e))(x)

Another way is to use the XOR binary operation as follows:

const symmetricDifferenceWithXor = <T>(e: Set<T>, f: Set<T>) => (x: T) => e(x) !== f(x)

Running the code below:

console.log('\nSymmetricDifference without XOR:')
const sdWithoutXor = core.symmetricDifferenceWithoutXor(numbers.prime, numbers.even)
console.log('Is 2 in the symetric difference of prime and even Sets? ', sdWithoutXor(2))
console.log('Is 4 in the symetric difference of prime and even Sets? ', sdWithoutXor(4))
console.log('Is 7 in the symetric difference of prime and even Sets? ', sdWithoutXor(7))

console.log('\nSymmetricDifference with XOR:')
const sdWithXor = core.symmetricDifferenceWithXor(numbers.prime, numbers.even)
console.log('Is 2 in the symetric difference of prime and even Sets? ', sdWithXor(2))
console.log('Is 4 in the symetric difference of prime and even Sets? ', sdWithXor(4))
console.log('Is 7 in the symetric difference of prime and even Sets? ', sdWithXor(7))

gives the following results:

Other Operations

This section presents other useful binary operations on sets.

Contains

Let Contains be the operation that checks whether or not an element is in a set. This operation is a function that takes as parameter an element and returns true if the element is in the set, false otherwise.

Thus, this operation is defined as follows in TypeScript:

const contains = <T>(e: Set<T>, x: T) => e(x)

Therefore, running the code below:

console.log('\nContains:')
console.log('Is 7 in the singleton {0}? ', core.contains(common.singleton(0), 7))
console.log('Is 7 in the singleton {7}? ', core.contains(common.singleton(7), 7))

gives the following result:

Add

Let Add be the operation that adds an element to a set. This operation is a function that takes as parameter an element and adds it to the set.

Thus, this operation is defined as follows in TypeScript:

const add = <T>(e: Set<T>, y: T) => (x: T) => x === y || e(x)

Therefore, running the code below:

console.log('\nAdd:')
console.log('Is 7 in {0, 7}? ', core.add<number>(common.singleton(0), 7)(7))
console.log('Is 0 in {1, 0}? ', core.add<number>(common.singleton(1), 0)(0))
console.log('Is 7 in {19, 0}? ', core.add<number>(common.singleton(19), 0)(7))

gives the following result:

Remove

Let Remove be the operation that removes an element from a set. This operations is a function that takes as parameter an element and removes it from the set.

Thus, this operation is defined as follows in TypeScript:

const remove = <T>(e: Set<T>, y: T) => (x: T) => x !== y && e(x)

Therefore, running the code below:

console.log('\nRemove:')
console.log('Is 7 in {}? ', core.remove<number>(common.singleton(0), 0)(7))
console.log('Is 0 in {}? ', core.remove<number>(common.singleton(7), 7)(0))

gives the following result:

For Those Who Want To Go Further

You can see how easy we can do some algebra of sets in TypeScript through Functional Programming. In the previous sections was shown the most fundamental definitions. But, If you want to go further, you can think about:

Relations over sets
Abstract algebra, such as monoids, groups, fields, rings, K-vectorial spaces and so on
Inclusion-exclusion principle
Russell's paradox
Cantor's paradox
Dual vector space
Theorems and Corollaries

Euclidean Plane

In the previous section, the fundamental concepts on sets were implemented in TypeScript. In this section, we will practice the concepts implemented on the Euclidean plane.

Drawing a Disk

In this section, we will set up the Characterstic function of the Closed disk and draw it in a HTML5 page.

To set up the Characterstic function, we first need a function that calculates the Euclidean Distance between two points in the plane. This function is implemented as follows:

function distance(p1: Point, p2: Point) {
    return Math.sqrt((p1.x - p2.x) ** 2 + (p1.y - p2.y) ** 2)
}

where Point is defined below:

class Point {
    x: number
    y: number

    constructor(x: number, y: number) {
        this.x = x
        this.y = y
    }
}

This formula is based on Pythagoras' Theorem.

where c is the Euclidean distance, a² is (p1.X - p2.X)² and b² is (p1.Y - p2.Y)².

Let Disk be the Characteristic function of a closed disk. In algebra of sets, the definition of a closed disk in the reals set is as follows:

where a and b are the coordinates of the center and R the radius.

Thus, the implementation of Disk in TypeScript is as follows:

const disk = (center: Point, radius: number) => (p: Point) => distance(p, center) <= radius

In order to view the set in a HTML5 page, I decided to implement a function draw that draws a set in the Euclidean plane. I chose HTML5 and thus used the canvas element for drawing.

Thus, I've built the Euclidean plane illustrated below through the method draw.

Below the implementation of the plane.

class Plane {
  width: number
  height: number

  constructor(width: number, height: number) {
    this.width = width
    this.height = height
  }

  draw(set: PlaneSet, canvasId: string) {
    const canvas = document.getElementById(canvasId) as HTMLCanvasElement
    if (!canvas) throw new Error(`Canvas with id ${canvasId} not found`)
    canvas.width = this.width
    canvas.height = this.height
    const context = canvas.getContext('2d') as CanvasRenderingContext2D
    const semiWidth = this.width / 2
    const semiHeight = this.height / 2
    const xMin = -semiWidth
    const xMax = semiWidth
    const yMin = -semiHeight
    const yMax = semiHeight
    for (let x = 0; x < this.width; x++) {
      const xp = xMin + (x * (xMax - xMin)) / this.width
      for (let y = 0; y < this.height; y++) {
        const yp = yMax - (y * (yMax - yMin)) / this.height
        if (set(new Point(xp, yp))) context.fillRect(x, y, 1, 1)
      }
    }
  }

  clear(canvasId: string) {
    const canvas = document.getElementById(canvasId) as HTMLCanvasElement
    if (!canvas) throw new Error(`Canvas with id ${canvasId} not found`)
    const context = canvas.getContext('2d') as CanvasRenderingContext2D
    context.clearRect(0, 0, this.width, this.height)
  }
}

In the draw function, a canvas having the same width and the same height as the Euclidean plane container is created. Then each point in pixels (x,y) of the canvas is replaced by a black point if it belongs to the set. xMin, xMax, yMin and yMax are the bounding values illustrated in the figure of the Euclidean plane above.

Running the code below:

euclideanPlane = new Plane(200, 200)
euclideanPlane.draw(disk(new Point(0, 0), 50), 'disk')

where disk is the id of the canvas:

<canvas id="disk"></canvas>

gives the following result:

Drawing Horizontal and Vertical Half-planes

In this section, we will set up the Characteristic functions of the horizontal and vertical half-planes, draw them in a HTML5 page and see what we can do if we combine them with the disk subset.

Let HorizontalHalfPlane be the Characteristic function of a horizontal half-plane. The implementation of HorizontalHalfPlane in TypeScript is as follows:

const horizontalHalfPlane = (y: number, isLowerThan: boolean) => 
      (p: Point) => (isLowerThan ? p.y <= y : p.y >= y)

Thus, running the code below:

euclideanPlane.draw(horizontalHalfPlane(0, true),'hhp')

where hhp is the id of the canvas:

<canvas id="hhp"></canvas>

gives the following result:

Let VerticalHalfPlane be the Characteristic function of a vertical half-plane. The implementation of VerticalHalfPlane in TypeScript is as follows:

jsconst verticalHalfPlane = (x: number, isLowerThan: boolean) => (p: Point) => (isLowerThan ? p.x <= x : p.x >= x)

Thus, running the code below:

euclideanPlane.draw(verticalHalfPlane(0, false),'vhp')

where vhd is the id of the canvas:

<canvas id="vhd"></canvas>

gives the following result:

In the first section of the article, we set up basic binary operations on sets. Thus, by combining the intersection of a disk and a half-plane for example, we can draw the half-disk subset.

Therefore, running the sample below:

euclideanPlane.draw(set.intersection(disk(new Point(0, 0), 50), 
                    verticalHalfPlane(0, false)), 'hd')

where hd is the id of the canvas:

<canvas id="hd"></canvas>

gives the following result:

Functions

This section presents functions on the sets in the Euclidean plane.

Translate

Let translatePoint be the function that translates a point in the plane. In Euclidean geometry, translatePoint is a function that moves a given point a constant distance in a specified direction. Thus the implementation in TypeScript is as follows:

const translatePoint = (deltax: number, deltay: number) => 
                       (p: Point) => new Point(p.x + deltax, p.y + deltay)

where (deltax, deltay) is the constant vector of the translation.

Let translate be the function that translates a set in the plane. This function is simply implemented as follows in TypeScript:

const translate = (e: PlaneSet, deltax: number, deltay: number) => 
                  (p: Point) => e(translatePoint(-deltax, -deltay)(p))

translate takes as parameters deltax which is the delta distance in the first Euclidean dimension and deltay which is the delta distance in the second Euclidean dimension. If a point P (x, y) is translated in a set S, then its coordinates will change to (x', y') = (x, delatx, y, deltay). Thus, the point (x' - delatx, y' - deltay) will always belong to the set S. In set algebra, translate is called isomorph, in other words, the set of all translations forms the translation group T, which is isomorphic to the space itself. This explains the main logic of the function.

Thus, running the code below in our HTML5 page:

let translate_timer: ReturnType<typeof setInterval>
function translate_op() {
  let deltay = 0
  clearTimeout(scale_timer)
  clearTimeout(rotate_timer)
  translate_timer = setInterval(() => {
    deltay = deltay <= euclideanPlane.height ? deltay + 20 : 0
    euclideanPlane.draw(translate(disk(new Point(0, -50), 50), 0, deltay), 'ep_op')
  }, 1000)
}

where ep_op is the id of the canvas:

<canvas id="ep_op"></canvas>

gives the following result:

Homothety

Let scalePoint be the function that sends any point M to another point N such that the segment SN is on the same line as SM, but scaled by a factor λ. In algebra of sets, Scale is formulated as follows:

Thus the implementation in TypeScript is as follows:

const scalePoint = (lambdax: number, lambday: number, deltax: number, deltay: number) 
      => (p: Point) => new Point(lambdax * p.x + deltax, lambday * p.y + deltay)

where (deltax, deltay) is the constant vector of the translation and (lambdax, lambday) is the lambda vector.

Let scale be the function that applies an homothety on a set in the plan. This function is simply implemented as follows in TypeScript:

const scale = (e: PlaneSet, lambdax: number, lambday: number, deltax: number, 
               deltay: number) => (p: Point) => e(scalePoint(1 / lambdax, 1 / lambday, 
               -deltax / lambdax, -deltay / lambday)(p))

scale takes as parameters deltax which is the delta distance in the first Euclidean dimension, deltay which is the delta distance in the second Euclidean dimension and (lambdax, lambday) which is the constant factor vector λ. If a point P (x, y) is transformed through scale in a set S, then its coordinates will change to (x', y') = (lambdax * x, delatx, lambday * y, deltay). Thus, the point ((x'- delatx)/lambdax, (y' - deltay)/lambday) will always belong to the set S, If lambda is different from the vector 0, of course. In algebra of sets, scale is called isomorph, in other words, the set of all homotheties forms the Homothety group H, which is isomorphic to the space itself \ {0}. This explains the main logic of the function.

Thus, running the code below in our HTML5 page:

let scale_timer: ReturnType<typeof setInterval>
function scale_op() {
  let deltay = 0
  let lambday = 0.05
  clearTimeout(translate_timer)
  clearTimeout(rotate_timer)
  scale_timer = setInterval(() => {
    deltay = deltay <= euclideanPlane.height ? deltay + 20 : 0
    lambday = deltay <= euclideanPlane.height ? lambday + 0.05 : 0.05
    euclideanPlane.draw(scale(disk(new Point(0, -50), 50), 1, lambday, 0, deltay), 'ep_op')
  }, 1000)
}

gives the following result:

Rotate

Let rotatePoint be the function that rotates a point with an angle θ. In matrix algebra, rotatePoint is formulated as follows:

where (x', y') are the co-ordinates of the point after rotation, and the formula for x' and y' is as follows:

The demonstration of this formula is very simple. Have a look at this rotation.

Below the demonstration:

Thus the implementation in TypeScript is as follows:

const rotatePoint = (theta: number) => (p: Point) => new Point(p.x * Math.cos(theta) 
      - p.y * Math.sin(theta), p.x * Math.sin(theta) + p.y * Math.cos(theta))

Let rotate be the function that applies a rotation on a set in the plane with the angle θ. This function is simply implemented as follows in TypeScript.

const rotate = (e: PlaneSet, theta: number) => (p: Point) => e(rotatePoint(-theta)(p))

rotate is a function that takes as parameter theta which is the angle of the rotation. If a point P (x, y) is transformed through rotate in a set S, then its coordinates will change to (x', y') = (x * cos(theta) - y * sin(theta), x * sin(theta), y * cos(theta)). Thus, the point (x' * cos(theta), y' * sin(theta), y' * cos(theta) - x' * sin(theta)) will always belong to the set S. In algebra of sets, rotate is called isomorph, in other words, the set of all rotations forms the Rotation group R, which is isomorphic to the space itself. This explains the main logic of the function.

Thus, running the code below in our HTML5 page:

let rotate_timer: ReturnType<typeof setInterval>
function rotate_op() {
  let theta = 0
  clearTimeout(translate_timer)
  clearTimeout(scale_timer)
  rotate_timer = setInterval(() => {
    euclideanPlane.draw(rotate(horizontalHalfPlane(-90, true), theta), 'ep_op')
    theta = (theta + Math.PI / 2) % (2 * Math.PI)
  }, 1000)
}

gives the following result:

For Those Who Want to Go Further

Very simple, isn't it? For those who want to go further, you can explore these:

Ellipse
Three-dimensional Euclidean space
Ellipsoide
Paraboloid
Hyperboloid
Spherical harmonics
Superellipsoid
Haumea
Homoeoid
Focaloid

Fractals

Pc(z) = z^2 + c

where c is a complex. The Mandelbrot fractal is defined as the set of all points c such that the above sequence does not escape to infinity. In algebra of sets, this is formulated as follows:

Fractals (abstract data type) can always be represented as follows in TypeScript:

type Fractal = (z: Complex, c: Complex) => Complex

Complex Numbers and Drawing

In order to be able to draw fractals, I needed to manipulate Complex numbers. Thus, I created the Complex class below:

class Complex {
    x: number
    y: number
    static zero = new Complex(0, 0)

    constructor(x: number, y: number) {
        this.x = x
        this.y = y
    }

    abs() {
        return Math.sqrt(this.x * this.x + this.y * this.y)
    }

    toString() {
        return this.x + ' + i * ' + this.y
    }
}

function add(z1: Complex, z2: Complex) {
    return new Complex(z1.x + z2.x, z1.y + z2.y)
}

function substract(z1: Complex, z2: Complex) {
    return new Complex(z1.x - z2.x, z1.y - z2.y)
}

function multiply(z1: Complex, z2: Complex) {
    return new Complex(z1.x * z2.x - z1.y * z2.y, z1.x * z2.y + z1.y * z2.x)
}

Mandelbrot Fractal

I created a Mandelbrot Fractal (abstract data type representation) P(z) = z^2 + c that is available below.

const mandelbrot = (z: Complex, c: Complex) => add(multiply(z, z), c)

In order to be able to draw Complex numbers, I created a ComplexPlane class. Below is the implementation in TypeScript.

class ComplexPlane {
  width: number
  height: number
  real_min: number
  real_max: number
  imaginary_min: number
  imaginary_max: number
  boundary: number
  fractalIterationsPerPixel: number
  canvasId: string

  constructor(
    width: number,
    height: number,
    real_min: number,
    real_max: number,
    imaginary_min: number,
    imaginary_max: number,
    boundary: number,
    fractalIterationsPerPixel: number,
    canvasId: string,
  ) {
    this.width = width
    this.height = height
    this.real_min = real_min
    this.real_max = real_max
    this.imaginary_min = imaginary_min
    this.imaginary_max = imaginary_max
    this.boundary = boundary
    this.fractalIterationsPerPixel = fractalIterationsPerPixel
    this.canvasId = canvasId
  }

  draw(fractal: Fractal) {
    const canvas = document.getElementById(this.canvasId) as HTMLCanvasElement
    canvas.width = this.width
    canvas.height = this.height
    const context = canvas.getContext('2d') as CanvasRenderingContext2D
    context.fillStyle = 'white'
    for (let x = 0; x < this.width; x++) {
      const xp = this.real_min + (x * (this.real_max - this.real_min)) / this.width
      for (let y = 0; y < this.height; y++) {
        const yp = this.imaginary_max - (y * (this.imaginary_max - this.imaginary_min)) / this.height
        const c = new Complex(xp, yp)
        let z = Complex.zero
        for (let k = 0; k < this.fractalIterationsPerPixel; k++) z = fractal(z, c)
        if (z.abs() < this.boundary) context.fillRect(x, y, 1, 1)
      }
    }
  }

  /*
   * Display 'Please wait...' at the center of the canvas
   *
  */
  pleaseWait() {
    const canvas = document.getElementById(this.canvasId) as HTMLCanvasElement
    canvas.width = this.width
    canvas.height = this.height
    const context = canvas.getContext('2d') as CanvasRenderingContext2D
    context.fillStyle = 'white'
    context.fillText('Please wait...', this.width / 2 - 30, this.height / 2)
  }
}

Thus, running the code below:

const complexPlane = new ComplexPlane(300, 300, -1.5, 1.5, -1.5, 1.5, 1.5, 20, 'fractal')

const mandelbrot = (z: Complex, c: Complex) => add(multiply(z, z), c)

complexPlane.pleaseWait()

setTimeout(() => complexPlane.draw(mandelbrot), 500)

where fractal is the id of the canvas:

<canvas id="fractal"></canvas>

gives the following result:

For Those Who Want to Go Further

For those who want to go further, you can explore these:

Newton Fractals
Julia Fractals
Other Fractals

Unit Tests

Below are the unit tests for sets of numbers.

import * as core from '../src/set.core'
import * as common from '../src/set.common'
import * as numbers from '../src/set.numbers'

describe('Test empty set', () => {
  it('should test empty set', () => {
    expect(common.empty<number>()(7)).toBeFalsy()
  })
})

describe('Test set all', () => {
  it('should test set all', () => {
    expect(common.all<number>()(7)).toBeTruthy()
  })
})

describe('Test singleton set', () => {
  it('should test singleton set', () => {
    expect(common.singleton(0)(7)).toBeFalsy()
    expect(common.singleton(7)(7)).toBeTruthy()
  })
})

describe('Test even numbers set', () => {
  it('should test even numbers set', () => {
    expect(numbers.even(99)).toBeFalsy()
    expect(numbers.even(998)).toBeTruthy()
  })
})

describe('Test odd numbers set', () => {
  it('should test odd numbers set', () => {
    expect(numbers.odd(99)).toBeTruthy()
    expect(numbers.odd(998)).toBeFalsy()
  })
})

describe('Test Multiples of 3 set', () => {
  it('should test Multiples of 3 set', () => {
    expect(numbers.multipleOfThree(99)).toBeTruthy()
    expect(numbers.multipleOfThree(998)).toBeFalsy()
  })
})

describe('Test Multiples of 5 set', () => {
  it('should test Multiples of 5 set', () => {
    expect(numbers.multipleOfFive(15)).toBeTruthy()
    expect(numbers.multipleOfFive(998)).toBeFalsy()
  })
})

describe('Test Primes set', () => {
  it('should test Primes set', () => {
    expect(numbers.prime(2)).toBeTruthy()
    expect(numbers.prime(4)).toBeFalsy()
    expect(numbers.getPrime(10001)).toBe(104743)
  })
})

describe('Test union', () => {
  it('should test union', () => {
    expect(core.union(numbers.even, numbers.odd)(7)).toBeTruthy()
  })
})

describe('Test intersection', () => {
  it('should test intersection', () => {
    const multiplesOfThreeAndFive = core.intersection(numbers.multipleOfThree, numbers.multipleOfFive)
    expect(multiplesOfThreeAndFive(15)).toBeTruthy()
    expect(multiplesOfThreeAndFive(10)).toBeFalsy()
  })
})

describe('Test Cartesian product', () => {
  it('should test Cartesian product', () => {
    const cp = core.cartesianProduct(numbers.multipleOfThree, numbers.multipleOfFive)
    expect(cp(9, 15)).toBeTruthy()
    expect(cp(10, 15)).toBeFalsy()
    expect(cp(9, 10)).toBeTruthy()
  })
})

describe('Test Complement', () => {
  it('should test Complement', () => {
    const c = core.complement(numbers.multipleOfThree, numbers.multipleOfFive)
    expect(c(15)).toBeFalsy()
    expect(c(9)).toBeTruthy()
  })
})

describe('Test Symetric difference without Xor', () => {
  it('should test Symetric difference without Xor', () => {
    const sdWithoutXor = core.symmetricDifferenceWithoutXor(numbers.prime, numbers.even)
    expect(sdWithoutXor(2)).toBeFalsy()
    expect(sdWithoutXor(4)).toBeTruthy()
    expect(sdWithoutXor(7)).toBeTruthy()
  })
})

describe('Test Symetric difference with Xor', () => {
  it('should test Symetric difference with Xor', () => {
    const sdWithXor = core.symmetricDifferenceWithXor(numbers.prime, numbers.even)
    expect(sdWithXor(2)).toBeFalsy()
    expect(sdWithXor(4)).toBeTruthy()
    expect(sdWithXor(7)).toBeTruthy()
  })
})

describe('Test Contains', () => {
  it('should test Contains', () => {
    expect(core.contains(common.singleton(0), 7)).toBeFalsy()
    expect(core.contains(common.singleton(7), 7)).toBeTruthy()
  })
})

describe('Test Add', () => {
  it('should test Add', () => {
    expect(core.contains(common.singleton(0), 7)).toBeFalsy()
    expect(core.add<number>(common.singleton(0), 7)(7)).toBeTruthy()
    expect(core.add<number>(common.singleton(1), 0)(0)).toBeTruthy()
    expect(core.add<number>(common.singleton(19), 0)(7)).toBeFalsy()
  })
})

describe('Test Remove', () => {
  it('should test Remove', () => {
    expect(core.remove<number>(common.singleton(0), 0)(7)).toBeFalsy()
    expect(core.remove<number>(common.singleton(7), 7)(0)).toBeFalsy()
    expect(core.remove<number>(common.all<number>(), 0)(0)).toBeFalsy()
    expect(core.remove<number>(common.all<number>(), 0)(7)).toBeTruthy()
  })
})

After running the unit tests with the following command:

npm test

We reach 100% of code coverage.

The coverage report is written in ./coverage folder.

That's it! I hope you enjoyed reading.

Microservices using ASP.NET Core, Ocelot, MongoDB and JWT

aelassas — Sat, 19 Oct 2024 15:31:08 +0000

Introduction
Best Practices
Development Environment
Prerequisites
Architecture
Source Code
Microservices
1. Catalog Microservice
2. Identity Microservice
3. Adding JWT to Catalog Microservice
4. Cart Microservice
API Gateways
Client Apps
Unit Tests
Monitoring using Health Checks
How to Run the Application
How to Deploy the Application
References
History

You can find source code here: https://github.com/aelassas/microservices

Introduction

A microservices architecture consists of a collection of small, independent, and loosely coupled services. Each service is self-contained, implements a single business capability, is responsible for persisting its own data, is a separate codebase, and can be deployed independently.

API gateways are entry points for clients. Instead of calling services directly, clients call the API gateway, which forwards the call to the appropriate services.

There are multiple advantages using microservices architecture:

Developers can better understand the functionality of a service.
Failure in one service does not impact other services.
It's easier to manage bug fixes and feature releases.
Services can be deployed in multiple servers to enhance performance.
Services are easy to change and test.
Services are easy and fast to deploy.
Allows to choose technology that is suited for a particular functionality.

Before choosing microservices architecture, here are some challenges to consider:

Services are simple but the entire system as a whole is more complex.
Communication between services can be complex.
More services equals more resources.
Global testing can be difficult.
Debugging can be harder.

Microservices architecture is great for large companies, but can be complicated for small companies who need to create and iterate quickly, and don't want to get into complex orchestration.

This article provides a comprehensive guide on building microservices using ASP.NET Core, constructing API gateways using Ocelot, establishing repositories using MongoDB, managing JWT in microservices, unit testing microservices using xUnit and Moq, monitoring microservices using health checks, and finally deploying microservices using Docker.

Best Practices

Here's a breakdown of some best practices:

Single Responsibility: Each microservice should have a single responsibility or purpose. This means that it should do one thing and do it well. This makes it easier to understand, develop, test, and maintain each microservice.
Separate Data Store: Microservices should ideally have their own data storage. This can be a separate database, which is isolated from other microservices. This isolation ensures that changes or issues in one microservice's data won't affect others.
Asynchronous Communication: Use asynchronous communication patterns, like message queues or publish-subscribe systems, to enable communication. This makes the system more resilient and decouples services from each other.
Containerization: Use containerization technologies like Docker to package and deploy microservices. Containers provide a consistent and isolated environment for your microservices, making it easier to manage and scale them.
Orchestration: Use container orchestration tools like Kubernetes to manage and scale your containers. Kubernetes provides features for load balancing, scaling, and monitoring, making it a great choice for orchestrating microservices.
Build and Deploy Separation: Keep the build and deployment processes separate. This means that the build process should result in a deployable artifact, like a Docker container image, which can then be deployed in different environments without modification.
Stateless: Microservices should be stateless as much as possible. Any necessary state should be stored in the database or an external data store. Stateless services are easier to scale and maintain.
Micro Frontends: If you're building a web application, consider using the micro frontends approach. This involves breaking down the user interface into smaller, independently deployable components that can be developed and maintained by separate teams.

Development Environment

Visual Studio 2022 >= 17.8.0
.NET 8.0
MongoDB
Postman

Prerequisites

C#
ASP.NET Core
Ocelot
Swashbuckle
Serilog
JWT
MongoDB
xUnit
Moq

Architecture

There are three microservices:

Catalog microservice: allows to manage the catalog.
Cart microservice: allows to manage the cart.
Identity microservice: allows to manage authentication and users.

Each microservice implements a single business capability and has its own dedicated database. This is called database-per-service pattern. This pattern allows for better separation of concerns, data isolation, and scalability. In a microservices architecture, services are designed to be small, focused, and independent, each responsible for a specific functionality. To maintain this separation, it's essential to ensure that each microservice manages its data independently. Here are other pros of this pattern:

Data schema can be modified without impacting other microservices.
Each microservice has its own data store, preventing accidental or unauthorized access to another service's data.
Since each microservice and its database are separate, they can be scaled independently based on their specific needs.
Each microservice can choose the database technology that best suits its requirements, without being bound to a single, monolithic database.
If one of the database server is down, this will not affect to other services.

There are two API gateways, one for the frontend and one for the backend.

Below is the frontend API gateway:

GET /catalog: retrieves catalog items.
GET /catalog/{id}: retrieves a catalog item.
GET /cart: retrieves cart items.
POST /cart: adds a cart item.
PUT /cart: updates a cart item.
DELETE /cart: deletes a cart item.
POST /identity/login: performs a login.
POST /identity/register: registers a user.
GET /identity/validate: validates a JWT token.

Below is the backend API gateway:

GET /catalog: retrieves catalog items.
GET /catalog/{id}: retrieves a catalog item.
POST /catalog: creates a catalog item.
PUT /catalog: updates a catalog item.
DELETE /catalog/{id}: deletes a catalog item.
PUT /cart/update-catalog-item: updates a catalog item in carts.
DELETE /cart/delete-catalog-item: deletes catalog item references from carts.
POST /identity/login: performs a login.
GET /identity/validate: validates a JWT token.

Finally, there are two client apps. A frontend for accessing the store and a backend for managing the store.

The frontend allows registered users to see the available catalog items, allows to add catalog items to the cart, and remove catalog items from the cart.

Here is a screenshot of the store page in the frontend:

The backend allows admin users to see the available catalog items, allows to add new catalog items, update catalog items, and remove catalog items.

Here is a screenshot of the store page in the backend:

Source Code

CatalogMicroservice project contains the source code of the microservice managing the catalog.
CartMicroservice project contains the source code of the microservice managing the cart.
IdentityMicroservice project contains the source code of the microservice managing authentication and users.
Middleware project contains the source code of common functionalities used by microservices.
FrontendGateway project contains the source code of the frontend API gateway.
BackendGateway project contains the source code of the backend API gateway.
Frontend project contains the source code of the frontend client app.
Backend project contains the source code of the backend client app.
test solution folder contains unit tests of all microservices.

Microservices and gateways are developed using ASP.NET Core and C#. Client apps are developed using HTML and Vanilla JavaScript in order to focus on microservices.

Microservices

Catalog Microservice

Let's start with the simplest microservice, CatalogMicroservice.

CatalogMicroservice is responsible for managing the catalog.

Below is the model used by CatalogMicroservice:


public class CatalogItem
{
    public static readonly string DocumentName = nameof(CatalogItem);

    [BsonId]
    [BsonRepresentation(BsonType.ObjectId)]
    public string? Id { get; init; }
    public required string Name { get; set; }
    public string? Description { get; set; }
    public decimal Price { get; set; }
}

Below is the repository interface:


public interface ICatalogRepository
{
    IList<CatalogItem> GetCatalogItems();
    CatalogItem? GetCatalogItem(string catalogItemId);
    void InsertCatalogItem(CatalogItem catalogItem);
    void UpdateCatalogItem(CatalogItem catalogItem);
    void DeleteCatalogItem(string catagItemId);
}

Below is the repository:


public class CatalogRepository(IMongoDatabase db) : ICatalogRepository
{
    private readonly IMongoCollection<CatalogItem> _col = 
                     db.GetCollection<CatalogItem>(CatalogItem.DocumentName);

    public IList<CatalogItem> GetCatalogItems() =>
        _col.Find(FilterDefinition<CatalogItem>.Empty).ToList();

    public CatalogItem GetCatalogItem(string catalogItemId) =>
        _col.Find(c => c.Id == catalogItemId).FirstOrDefault();

    public void InsertCatalogItem(CatalogItem catalogItem) =>
        _col.InsertOne(catalogItem);

    public void UpdateCatalogItem(CatalogItem catalogItem) =>
        _col.UpdateOne(c => c.Id == catalogItem.Id, Builders<CatalogItem>.Update
            .Set(c => c.Name, catalogItem.Name)
            .Set(c => c.Description, catalogItem.Description)
            .Set(c => c.Price, catalogItem.Price));

    public void DeleteCatalogItem(string catalogItemId) =>
        _col.DeleteOne(c => c.Id == catalogItemId);
}

Below is the controller:


[Route("api/[controller]")]
[ApiController]
public class CatalogController(ICatalogRepository catalogRepository) : ControllerBase
{
    // GET: api/<CatalogController>
    [HttpGet]
    public IActionResult Get()
    {
        var catalogItems = catalogRepository.GetCatalogItems();
        return Ok(catalogItems);
    }

    // GET api/<CatalogController>/653e4410614d711b7fc953a7
    [HttpGet("{id}")]
    public IActionResult Get(string id)
    {
        var catalogItem = catalogRepository.GetCatalogItem(id);
        return Ok(catalogItem);
    }

    // POST api/<CatalogController>
    [HttpPost]
    public IActionResult Post([FromBody] CatalogItem catalogItem)
    {
        catalogRepository.InsertCatalogItem(catalogItem);
        return CreatedAtAction(nameof(Get), new { id = catalogItem.Id }, catalogItem);
    }

    // PUT api/<CatalogController>
    [HttpPut]
    public IActionResult Put([FromBody] CatalogItem? catalogItem)
    {
        if (catalogItem != null)
        {
            catalogRepository.UpdateCatalogItem(catalogItem);
            return Ok();
        }
        return new NoContentResult();
    }

    // DELETE api/<CatalogController>/653e4410614d711b7fc953a7
    [HttpDelete("{id}")]
    public IActionResult Delete(string id)
    {
        catalogRepository.DeleteCatalogItem(id);
        return Ok();
    }
}

ICatalogRepository is added using dependency injection in Startup.cs in order to make the microservice testable:


// This method gets called by the runtime. 
// Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddMongoDb(Configuration);
    services.AddSingleton<ICatalogRepository>(sp =>
        new CatalogRepository(sp.GetService<IMongoDatabase>() ?? 
            throw new Exception("IMongoDatabase not found"))
    );
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Catalog", Version = "v1" });
    });

    // ...
}

Below is AddMongoDB extension method:


public static void AddMongoDb
  (this IServiceCollection services, IConfiguration configuration)
{
    services.Configure<MongoOptions>(configuration.GetSection("mongo"));
    services.AddSingleton(c =>
    {
        var options = c.GetService<IOptions<MongoOptions>>();

        return new MongoClient(options.Value.ConnectionString);
    });
    services.AddSingleton(c =>
    {
        var options = c.GetService<IOptions<MongoOptions>>();
        var client = c.GetService<MongoClient>();

        return client.GetDatabase(options.Value.Database);
    });
}

Below is Configure method in Startup.cs:

// This method gets called by the runtime. 
// Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseSwagger();

    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Catalog V1");
    });

    var option = new RewriteOptions();
    option.AddRedirect("^$", "swagger");
    app.UseRewriter(option);

    // ...

    app.UseHttpsRedirection();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Below is appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "mongo": {
    "connectionString": "mongodb://127.0.0.1:27017",
    "database": "store-catalog"
  }
}

API documentation is generated using Swashbuckle. Swagger middleware is configured in Startup.cs, in ConfigureServices and Configure methods in Startup.cs.

If you run CatalogMicroservice project using IISExpress or Docker, you will get the Swagger UI when accessing http://localhost:44326/:

Identity Microservice

Now, let's move on to IdentityMicroservice.

IdentityMicroservice is responsible for authentication and managing users.

Below is the model used by IdentityMicroservice:

public class User
{
    public static readonly string DocumentName = nameof(User);

    [BsonId]
    [BsonRepresentation(BsonType.ObjectId)]
    public string? Id { get; init; }
    public required string Email { get; init; }
    public required string Password { get; set; }
    public string? Salt { get; set; }
    public bool IsAdmin { get; init; }

    public void SetPassword(string password, IEncryptor encryptor)
    {
        Salt = encryptor.GetSalt();
        Password = encryptor.GetHash(password, Salt);
    }

    public bool ValidatePassword(string password, IEncryptor encryptor) =>
        Password == encryptor.GetHash(password, Salt);
}

IEncryptor middleware is used for encrypting passwords.

Below is the repository interface:

public interface IUserRepository
{
    User? GetUser(string email);
    void InsertUser(User user);
}

Below is the repository implementation:

public class UserRepository(IMongoDatabase db) : IUserRepository
{
    private readonly IMongoCollection<User> _col = 
                     db.GetCollection<User>(User.DocumentName);

    public User? GetUser(string email) =>
        _col.Find(u => u.Email == email).FirstOrDefault();

    public void InsertUser(User user) =>
        _col.InsertOne(user);
}

Below is the controller:

[Route("api/[controller]")]
[ApiController]
public class IdentityController
  (IUserRepository userRepository, IJwtBuilder jwtBuilder, IEncryptor encryptor)
    : ControllerBase
{
    [HttpPost("login")]
    public IActionResult Login([FromBody] User user, 
           [FromQuery(Name = "d")] string destination = "frontend")
    {
        var u = userRepository.GetUser(user.Email);

        if (u == null)
        {
            return NotFound("User not found.");
        }

        if (destination == "backend" && !u.IsAdmin)
        {
            return BadRequest("Could not authenticate user.");
        }

        var isValid = u.ValidatePassword(user.Password, encryptor);

        if (!isValid)
        {
            return BadRequest("Could not authenticate user.");
        }

        var token = jwtBuilder.GetToken(u.Id);

        return Ok(token);
    }

    [HttpPost("register")]
    public IActionResult Register([FromBody] User user)
    {
        var u = userRepository.GetUser(user.Email);

        if (u != null)
        {
            return BadRequest("User already exists.");
        }

        user.SetPassword(user.Password, encryptor);
        userRepository.InsertUser(user);

        return Ok();
    }

    [HttpGet("validate")]
    public IActionResult Validate([FromQuery(Name = "email")] string email, 
                                  [FromQuery(Name = "token")] string token)
    {
        var u = userRepository.GetUser(email);

        if (u == null)
        {
            return NotFound("User not found.");
        }

        var userId = jwtBuilder.ValidateToken(token);

        if (userId != u.Id)
        {
            return BadRequest("Invalid token.");
        }

        return Ok(userId);
    }
}

IUserRepository, IJwtBuilder and IEncryptor middlewares are added using dependency injection in Startup.cs:

// This method gets called by the runtime. 
// Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddMongoDb(Configuration);
    services.AddJwt(Configuration);
    services.AddTransient<IEncryptor, Encryptor>();
    services.AddSingleton<IUserRepository>(sp =>
        new UserRepository(sp.GetService<IMongoDatabase>() ?? 
            throw new Exception("IMongoDatabase not found"))
    );
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "User", Version = "v1" });
    });

    // ...
}

Below is AddJwt extension method:

public static void AddJwt(this IServiceCollection services, IConfiguration configuration)
{
    var options = new JwtOptions();
    var section = configuration.GetSection("jwt");
    section.Bind(options);
    services.Configure<JwtOptions>(section);
    services.AddSingleton<IJwtBuilder, JwtBuilder>();
    services.AddAuthentication()
        .AddJwtBearer(cfg =>
        {
            cfg.RequireHttpsMetadata = false;
            cfg.SaveToken = true;
            cfg.TokenValidationParameters = new TokenValidationParameters
            {
                ValidateAudience = false,
                IssuerSigningKey = new SymmetricSecurityKey
                                   (Encoding.UTF8.GetBytes(options.Secret))
            };
        });
}

IJwtBuilder is responsible for creating JWT tokens and validating them:

public interface IJwtBuilder
{
    string GetToken(string userId);
    string ValidateToken(string token);
}

Below is the implementation of IJwtBuilder:

public class JwtBuilder(IOptions<JwtOptions> options) : IJwtBuilder
{
    private readonly JwtOptions _options = options.Value;

    public string GetToken(string userId)
    {
        var signingKey = new SymmetricSecurityKey
                         (Encoding.UTF8.GetBytes(_options.Secret));
        var signingCredentials = new SigningCredentials
                                 (signingKey, SecurityAlgorithms.HmacSha256);
        var claims = new[]
        {
            new Claim("userId", userId)
        };
        var expirationDate = DateTime.Now.AddMinutes(_options.ExpiryMinutes);
        var jwt = new JwtSecurityToken(claims: claims, 
                  signingCredentials: signingCredentials, expires: expirationDate);
        var encodedJwt = new JwtSecurityTokenHandler().WriteToken(jwt);

        return encodedJwt;
    }

    public string ValidateToken(string token)
    {
        var principal = GetPrincipal(token);
        if (principal == null)
        {
            return string.Empty;
        }

        ClaimsIdentity identity;
        try
        {
            identity = (ClaimsIdentity)principal.Identity;
        }
        catch (NullReferenceException)
        {
            return string.Empty;
        }
        var userIdClaim = identity?.FindFirst("userId");
        if (userIdClaim == null)
        {
            return string.Empty;
        }
        var userId = userIdClaim.Value;
        return userId;
    }

    private ClaimsPrincipal GetPrincipal(string token)
    {
        try
        {
            var tokenHandler = new JwtSecurityTokenHandler();
            var jwtToken = (JwtSecurityToken)tokenHandler.ReadToken(token);
            if (jwtToken == null)
            {
                return null;
            }
            var key = Encoding.UTF8.GetBytes(_options.Secret);
            var parameters = new TokenValidationParameters()
            {
                RequireExpirationTime = true,
                ValidateIssuer = false,
                ValidateAudience = false,
                IssuerSigningKey = new SymmetricSecurityKey(key)
            };
            IdentityModelEventSource.ShowPII = true;
            ClaimsPrincipal principal = 
                  tokenHandler.ValidateToken(token, parameters, out _);
            return principal;
        }
        catch (Exception)
        {
            return null;
        }
    }
}

IEncryptor is simply responsible for encrypting passwords:

public interface IEncryptor
{
    string GetSalt();
    string GetHash(string value, string salt);
}

Below is the implementation of IEncryptor:

public class Encryptor: IEncryptor
{
    private const int SALT_SIZE = 40;
    private const int ITERATIONS_COUNT = 10000;

    public string GetSalt()
    {
        var saltBytes = new byte[SALT_SIZE];
        var rng = RandomNumberGenerator.Create();
        rng.GetBytes(saltBytes);

        return Convert.ToBase64String(saltBytes);
    }

    public string GetHash(string value, string salt)
    {
        var pbkdf2 = new Rfc2898DeriveBytes
            (value, GetBytes(salt), ITERATIONS_COUNT, HashAlgorithmName.SHA256);

        return Convert.ToBase64String(pbkdf2.GetBytes(SALT_SIZE));
    }

    private static byte[] GetBytes(string value)
    {
        var bytes = new byte[value.Length + sizeof(char)];
        Buffer.BlockCopy(value.ToCharArray(), 0, bytes, 0, bytes.Length);

        return bytes;
    }
}

Below is Configure method in Startup.cs:

// This method gets called by the runtime. 
// Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseSwagger();

    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Catalog V1");
    });

    var option = new RewriteOptions();
    option.AddRedirect("^$", "swagger");
    app.UseRewriter(option);

    // ...

    app.UseHttpsRedirection();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Below is appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "mongo": {
    "connectionString": "mongodb://127.0.0.1:27017",
    "database": "store-identity"
  },
  "jwt": {
    "secret": "9095a623-a23a-481a-aa0c-e0ad96edc103",
    "expiryMinutes": 60
  }
}

Now, let's test IdentityMicroservice.

Open Postman and execute the following POST request http://localhost:44397/api/identity/register with the following payload to register a user:

{
  "email": "user@store.com",
  "password": "pass"
}

Now, execute the following POST request http://localhost:44397/api/identity/login with the following payload to create a JWT token:

{
  "email": "user@store.com",
  "password": "pass"
}

You can then check the generated token on jwt.io:

That's it. You can execute the following GET request http://localhost:44397/api/identity/validate?email={email}&token={token} in the same way to validate a JWT token. If the token is valid, the response will be the user Id which is an ObjectId.

If you run IdentityMicroservice project using IISExpress or Docker, you will get the Swagger UI when accessing http://localhost:44397/:

Adding JWT to Catalog Microservice

Now, let's add JWT authentication to catalog microservice.

First, we have to add jwt section in appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "jwt": {
    "secret": "9095a623-a23a-481a-aa0c-e0ad96edc103"
  },
  "mongo": {
    "connectionString": "mongodb://127.0.0.1:27017",
    "database": "store-catalog"
  }
}

Then, we have to add JWT configuration in ConfigureServices method in Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    services.AddJwtAuthentication(Configuration); // JWT Configuration

    // ...
}

Where AddJwtAuthentication extension method is implemented as follows:

public static void AddJwtAuthentication
    (this IServiceCollection services, IConfiguration configuration)
{
    var section = configuration.GetSection("jwt");
    var options = section.Get<JwtOptions>();
    var key = Encoding.UTF8.GetBytes(options.Secret);
    section.Bind(options);
    services.Configure<JwtOptions>(section);

    services.AddSingleton<IJwtBuilder, JwtBuilder>();
    services.AddTransient<JwtMiddleware>();

    services.AddAuthentication(x =>
        {
            x.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            x.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
        .AddJwtBearer(x =>
        {
            x.RequireHttpsMetadata = false;
            x.SaveToken = true;
            x.TokenValidationParameters = new TokenValidationParameters
            {
                ValidateIssuerSigningKey = true,
                IssuerSigningKey = new SymmetricSecurityKey(key),
                ValidateIssuer = false,
                ValidateAudience = false
            };
        });

    services.AddAuthorization(x =>
    {
        x.DefaultPolicy = new AuthorizationPolicyBuilder()
            .AddAuthenticationSchemes(JwtBearerDefaults.AuthenticationScheme)
            .RequireAuthenticatedUser()
            .Build();
    });
}

JwtMiddleware is responsible for validating JWT token:

public class JwtMiddleware(IJwtBuilder jwtBuilder) : IMiddleware
{
    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        // Get the token from the Authorization header
        var bearer = context.Request.Headers["Authorization"].ToString();
        var token = bearer.Replace("Bearer ", string.Empty);

        if (!string.IsNullOrEmpty(token))
        {
            // Verify the token using the IJwtBuilder
            var userId = jwtBuilder.ValidateToken(token);

            if (ObjectId.TryParse(userId, out _))
            {
                // Store the userId in the HttpContext items for later use
                context.Items["userId"] = userId;
            }
            else
            {
                // If token or userId are invalid, send 401 Unauthorized status
                context.Response.StatusCode = 401;
            }
        }

        // Continue processing the request
        await next(context);
    }
}

If the JWT token or the user ID are invalid, we send 401 Unauthorized status.

Then, we resigster JwtMiddleware in Configure method in Startup.cs:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ...

    app.UseMiddleware<JwtMiddleware>(); // JWT Middleware

    app.UseAuthentication();

    app.UseAuthorization();

    // ...
}

Then, we specify that we require JWT authentication for our endpoints in CatalogController.cs through [Authorize] attribute:

// GET: api/<CatalogController>
[HttpGet]
[Authorize]
public IActionResult Get()
{
    var catalogItems = _catalogRepository.GetCatalogItems();
    return Ok(catalogItems);
}

// ...

Now, catalog microservice is secured through JWT authentication. Cart microservice was secured in the same way.

Finally, we need to add JWT authentication to Swagger. To do so, we need to update AddSwaggerGen in ConfigureServices in Statup.cs:

public void ConfigureServices(IServiceCollection services)
{
    //...

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Catalog", Version = "v1" });
        c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
        {
            In = ParameterLocation.Header,
            Description = "Please insert JWT token with the prefix Bearer into field",
            Name = "Authorization",
            Type = SecuritySchemeType.ApiKey,
            Scheme = "bearer",
            BearerFormat = "JWT"
        });
        c.AddSecurityRequirement(new OpenApiSecurityRequirement {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference
                    {
                        Type = ReferenceType.SecurityScheme,
                        Id = "Bearer"
                    }
                },
                new string[] { }
            }
        });
    });

    //...
}

Now if you want to run Postman on catalog or cart microservices, you need to specify the Bearer Token in Authorization tab.

If you want to test catalog or cart microservices with Swagger, you need to click on Authorize button and enter the JWT token with the prefix Bearer into authorization field.

Cart Microservice

CartMicroservice is responsible for managing the cart.

Below are the models used by CartMicroservice:

public class Cart
{
    public static readonly string DocumentName = nameof(Cart);

    [BsonId]
    [BsonRepresentation(BsonType.ObjectId)]
    public string? Id { get; init; }
    [BsonRepresentation(BsonType.ObjectId)]
    public string? UserId { get; init; }
    public List<CartItem> CartItems { get; init; } = new();
}

public class CartItem
{
    [BsonRepresentation(BsonType.ObjectId)]
    public string? CatalogItemId { get; init; }
    public required string Name { get; set; }
    public decimal Price { get; set; }
    public int Quantity { get; set; }
}

Below is the repository interface:

public interface ICartRepository
{
    IList<CartItem> GetCartItems(string userId);
    void InsertCartItem(string userId, CartItem cartItem);
    void UpdateCartItem(string userId, CartItem cartItem);
    void DeleteCartItem(string userId, string cartItemId);
    void UpdateCatalogItem(string catalogItemId, string name, decimal price);
    void DeleteCatalogItem(string catalogItemId);
}

Below is the repository:

public class CartRepository(IMongoDatabase db) : ICartRepository
{
    private readonly IMongoCollection<Cart> _col = 
                           db.GetCollection<Cart>(Cart.DocumentName);

    public IList<CartItem> GetCartItems(string userId) =>
        _col
        .Find(c => c.UserId == userId)
        .FirstOrDefault()?.CartItems ?? new List<CartItem>();

    public void InsertCartItem(string userId, CartItem cartItem)
    {
        var cart = _col.Find(c => c.UserId == userId).FirstOrDefault();
        if (cart == null)
        {
            cart = new Cart
            {
                UserId = userId,
                CartItems = new List<CartItem> { cartItem }
            };
            _col.InsertOne(cart);
        }
        else
        {
            var ci = cart
                .CartItems
                .FirstOrDefault(ci => ci.CatalogItemId == cartItem.CatalogItemId);

            if (ci == null)
            {
                cart.CartItems.Add(cartItem);
            }
            else
            {
                ci.Quantity++;
            }

            var update = Builders<Cart>.Update
                .Set(c => c.CartItems, cart.CartItems);
            _col.UpdateOne(c => c.UserId == userId, update);
        }
    }

    public void UpdateCartItem(string userId, CartItem cartItem)
    {
        var cart = _col.Find(c => c.UserId == userId).FirstOrDefault();
        if (cart != null)
        {
            cart.CartItems.RemoveAll(ci => ci.CatalogItemId == cartItem.CatalogItemId);
            cart.CartItems.Add(cartItem);
            var update = Builders<Cart>.Update
                .Set(c => c.CartItems, cart.CartItems);
            _col.UpdateOne(c => c.UserId == userId, update);
        }
    }

    public void DeleteCartItem(string userId, string catalogItemId)
    {
        var cart = _col.Find(c => c.UserId == userId).FirstOrDefault();
        if (cart != null)
        {
            cart.CartItems.RemoveAll(ci => ci.CatalogItemId == catalogItemId);
            var update = Builders<Cart>.Update
                .Set(c => c.CartItems, cart.CartItems);
            _col.UpdateOne(c => c.UserId == userId, update);
        }
    }

    public void UpdateCatalogItem(string catalogItemId, string name, decimal price)
    {
        // Update catalog item in carts
        var carts = GetCarts(catalogItemId);
        foreach (var cart in carts)
        {
            var cartItem = cart.CartItems.FirstOrDefault
                           (i => i.CatalogItemId == catalogItemId);
            if (cartItem != null)
            {
                cartItem.Name = name;
                cartItem.Price = price;
                var update = Builders<Cart>.Update
                    .Set(c => c.CartItems, cart.CartItems);
                _col.UpdateOne(c => c.Id == cart.Id, update);
            }
        }
    }

    public void DeleteCatalogItem(string catalogItemId)
    {
        // Delete catalog item from carts
        var carts = GetCarts(catalogItemId);
        foreach (var cart in carts)
        {
            cart.CartItems.RemoveAll(i => i.CatalogItemId == catalogItemId);
            var update = Builders<Cart>.Update
                .Set(c => c.CartItems, cart.CartItems);
            _col.UpdateOne(c => c.Id == cart.Id, update);
        }
    }

    private IList<Cart> GetCarts(string catalogItemId) =>
        _col.Find(c => c.CartItems.Any(i => i.CatalogItemId == catalogItemId)).ToList();
}

Below is the controller:

[Route("api/[controller]")]
[ApiController]
public class CartController(ICartRepository cartRepository) : ControllerBase
{
    // GET: api/<CartController>
    [HttpGet]
    [Authorize]
    public IActionResult Get([FromQuery(Name = "u")] string userId)
    {
        var cartItems = cartRepository.GetCartItems(userId);
        return Ok(cartItems);
    }

    // POST api/<CartController>
    [HttpPost]
    [Authorize]
    public IActionResult Post([FromQuery(Name = "u")] string userId, 
                              [FromBody] CartItem cartItem)
    {
        cartRepository.InsertCartItem(userId, cartItem);
        return Ok();
    }

    // PUT api/<CartController>
    [HttpPut]
    [Authorize]
    public IActionResult Put([FromQuery(Name = "u")] string userId, 
                             [FromBody] CartItem cartItem)
    {
        cartRepository.UpdateCartItem(userId, cartItem);
        return Ok();
    }

    // DELETE api/<CartController>
    [HttpDelete]
    [Authorize]
    public IActionResult Delete([FromQuery(Name = "u")] string userId, 
                                [FromQuery(Name = "ci")] string cartItemId)
    {
        cartRepository.DeleteCartItem(userId, cartItemId);
        return Ok();
    }

    // PUT api/<CartController>/update-catalog-item
    [HttpPut("update-catalog-item")]
    [Authorize]
    public IActionResult Put([FromQuery(Name = "ci")] string catalogItemId, 
    [FromQuery(Name = "n")] string name, [FromQuery(Name = "p")] decimal price)
    {
        cartRepository.UpdateCatalogItem(catalogItemId, name, price);
        return Ok();
    }

    // DELETE api/<CartController>/delete-catalog-item
    [HttpDelete("delete-catalog-item")]
    [Authorize]
    public IActionResult Delete([FromQuery(Name = "ci")] string catalogItemId)
    {
        cartRepository.DeleteCatalogItem(catalogItemId);
        return Ok();
    }
}

ICartRepository is added using dependency injection in Startup.cs in order to make the microservice testable:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    services.AddJwtAuthentication(Configuration); // JWT Configuration

    services.AddMongoDb(Configuration);

    services.AddSingleton<ICartRepository>(sp =>
        new CartRepository(sp.GetService<IMongoDatabase>() ?? 
            throw new Exception("IMongoDatabase not found"))
    );

    // ...
}

Configure method in Startup.cs is the same as the one in CatalogMicroservice.

Below is appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "jwt": {
    "secret": "9095a623-a23a-481a-aa0c-e0ad96edc103"
  },
  "mongo": {
    "connectionString": "mongodb://127.0.0.1:27017",
    "database": "store-cart"
  }
}

API documentation is generated using Swashbuckle. Swagger middleware is configured in Startup.cs, in ConfigureServices and Configure methods in Startup.cs.

If you run CartMicroservice project using IISExpress or Docker, you will get the Swagger UI when accessing http://localhost:44388/.

API Gateways

There are two API gateways, one for the frontend and one for the backend.

Let's start with the frontend.

ocelot.json configuration file was added in Program.cs as follows:

var builder = Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config
                .SetBasePath(hostingContext.HostingEnvironment.ContentRootPath)
                .AddJsonFile("appsettings.json", true, true)
                .AddJsonFile("ocelot.json", false, true)
                .AddJsonFile($"appsettings.
                {hostingContext.HostingEnvironment.EnvironmentName}.json", true, true)
                .AddJsonFile($"ocelot.
                {hostingContext.HostingEnvironment.EnvironmentName}.json", 
                 optional: false, reloadOnChange: true)
                .AddEnvironmentVariables();

            if (hostingContext.HostingEnvironment.EnvironmentName == "Development")
            {
                config.AddJsonFile("appsettings.Local.json", true, true);
            }
        })
        .UseSerilog((_, config) =>
        {
            config
                .MinimumLevel.Information()
                .MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
                .Enrich.FromLogContext()
                .WriteTo.Console();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

builder.Build().Run();

Serilog is configured to write logs to the console. You can, of course, write logs to text files using WriteTo.File(@"Logs\store.log") and Serilog.Sinks.File nuget package.

Then, here is Startup.cs:

public class Startup(IConfiguration configuration)
{
    private IConfiguration Configuration { get; } = configuration;

    // This method gets called by the runtime. 
    // Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();

        services.AddOcelot(Configuration);

        services.AddJwtAuthentication(Configuration); // JWT Configuration

        services.AddCors(options =>
        {
            options.AddPolicy("CorsPolicy",
                builder => builder.AllowAnyOrigin()
                    .AllowAnyMethod()
                    .AllowAnyHeader());
        });

        services.AddHealthChecks()
            .AddMongoDb(
                mongodbConnectionString: (
                    Configuration.GetSection("mongo").Get<MongoOptions>()
                    ?? throw new Exception("mongo configuration section not found")
                ).ConnectionString,
                name: "mongo",
                failureStatus: HealthStatus.Unhealthy
            );

        services.AddHealthChecksUI().AddInMemoryStorage();
    }

    // This method gets called by the runtime. Use this method 
    // to configure the HTTP request pipeline.
    public async void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseMiddleware<RequestResponseLogging>();

        app.UseCors("CorsPolicy");

        app.UseAuthentication();

        app.UseHealthChecks("/healthz", new HealthCheckOptions
        {
            Predicate = _ => true,
            ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
        });

        app.UseHealthChecksUI();

        var option = new RewriteOptions();
        option.AddRedirect("^$", "healthchecks-ui");
        app.UseRewriter(option);

        await app.UseOcelot();
    }
}

RequestResponseLogging middleware is responsible for logging requests and responses:

public class RequestResponseLogging(RequestDelegate next, ILogger<RequestResponseLogging> logger)
{
    public async Task InvokeAsync(HttpContext context)
    {
        context.Request.EnableBuffering();
        var builder = new StringBuilder();
        var request = await FormatRequest(context.Request);
        builder.Append("Request: ").AppendLine(request);
        builder.AppendLine("Request headers:");

        foreach (var header in context.Request.Headers)
        {
            builder.Append(header.Key).Append(": ").AppendLine(header.Value);
        }

        var originalBodyStream = context.Response.Body;
        using var responseBody = new MemoryStream();
        context.Response.Body = responseBody;
        await next(context);

        var response = await FormatResponse(context.Response);
        builder.Append("Response: ").AppendLine(response);
        builder.AppendLine("Response headers: ");

        foreach (var header in context.Response.Headers)
        {
            builder.Append(header.Key).Append(": ").AppendLine(header.Value);
        }

        logger.LogInformation(builder.ToString());

        await responseBody.CopyToAsync(originalBodyStream);
    }

    private static async Task<string> FormatRequest(HttpRequest request)
    {
        using var reader = new StreamReader(
            request.Body,
            encoding: Encoding.UTF8,
            detectEncodingFromByteOrderMarks: false,
            leaveOpen: true);
        var body = await reader.ReadToEndAsync();
        var formattedRequest = $"{request.Method} 
        {request.Scheme}://{request.Host}{request.Path}{request.QueryString} {body}";
        request.Body.Position = 0;
        return formattedRequest;
    }

    private static async Task<string> FormatResponse(HttpResponse response)
    {
        response.Body.Seek(0, SeekOrigin.Begin);
        string text = await new StreamReader(response.Body).ReadToEndAsync();
        response.Body.Seek(0, SeekOrigin.Begin);
        return $"{response.StatusCode}: {text}";
    }
}

We used logging in the gateway so that we don't need to check the logs of each microservice.

Here is ocelot.Development.json:

{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/catalog",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 44326
        }
      ],
      "UpstreamPathTemplate": "/catalog",
      "UpstreamHttpMethod": [ "GET" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    },
    {
      "DownstreamPathTemplate": "/api/catalog/{id}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 44326
        }
      ],
      "UpstreamPathTemplate": "/catalog/{id}",
      "UpstreamHttpMethod": [ "GET" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    },
    {
      "DownstreamPathTemplate": "/api/cart",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 44388
        }
      ],
      "UpstreamPathTemplate": "/cart",
      "UpstreamHttpMethod": [ "GET" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    },
    {
      "DownstreamPathTemplate": "/api/cart",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 44388
        }
      ],
      "UpstreamPathTemplate": "/cart",
      "UpstreamHttpMethod": [ "POST" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    },
    {
      "DownstreamPathTemplate": "/api/cart",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 44388
        }
      ],
      "UpstreamPathTemplate": "/cart",
      "UpstreamHttpMethod": [ "PUT" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    },
    {
      "DownstreamPathTemplate": "/api/cart",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 44388
        }
      ],
      "UpstreamPathTemplate": "/cart",
      "UpstreamHttpMethod": [ "DELETE" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    },
    {
      "DownstreamPathTemplate": "/api/identity/login",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 44397
        }
      ],
      "UpstreamPathTemplate": "/identity/login",
      "UpstreamHttpMethod": [ "POST" ]
    },
    {
      "DownstreamPathTemplate": "/api/identity/register",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 44397
        }
      ],
      "UpstreamPathTemplate": "/identity/register",
      "UpstreamHttpMethod": [ "POST" ]
    },
    {
      "DownstreamPathTemplate": "/api/identity/validate",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 44397
        }
      ],
      "UpstreamPathTemplate": "/identity/validate",
      "UpstreamHttpMethod": [ "GET" ]
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "http://localhost:44300/"
  }
}

And finally, below is appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "jwt": {
    "secret": "9095a623-a23a-481a-aa0c-e0ad96edc103"
  },
  "mongo": {
    "connectionString": "mongodb://127.0.0.1:27017"
  }
}

Now, let's test the frontend gateway.

First, execute the following POST request http//localhost:44300/identity/login with the following payload to create a JWT token:

{
  "email": "user@store.com",
  "password": "pass"
}

We already created that user while testing IdentityMicroservice. If you didn't create that user, you can create one by executing the following POST request http://localhost:44300/identity/register with the same payload above.

Then, go to Authorization tab in Postman, select Bearer Token type and copy paste the JWT token in Token field. Then, execute the following GET request to retrieve the catalog http://localhost:44300/catalog:

If the JWT token is not valid, the response will be 401 Unauthorized.

You can check the tokens on jwt.io:

If we open the console in Visual Studio, we can see all the logs:

That's it! You can test the other API methods in the same way.

The backend gateway is done pretty much the same way. The only difference is in ocelot.json file.

Client Apps

There are two client apps. One for the frontend and one for the backend.

The client apps are made using HTML and Vanilla JavaScript for the sake of simplicity.

Let's pick the login page of the frontend for example. Here is the HTML:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>Login</title>
    <link rel="icon" href="data:,">
    <link href="css/bootstrap.min.css" rel="stylesheet" />
    <link href="css/login.css" rel="stylesheet" />
</head>
<body>
    <div class="header"></div>
    <div class="login">
        <table>
            <tr>
                <td>Email</td>
                <td><input id="email" type="text" autocomplete="off" 
                                      class="form-control" /></td>
            </tr>
            <tr>
                <td>Password</td>
                <td><input id="password" type="password" class="form-control" /></td>
            </tr>
            <tr>
                <td></td>
                <td>
                    <input id="login" type="button" value="Login" 
                                         class="btn btn-primary" />
                    <input id="register" type="button" value="Register" 
                                         class="btn btn-secondary" />
                </td>
            </tr>
        </table>
    </div>
    <script src="js/login.js" type="module"></script>
</body>
</html>

Here is settings.js:

export default {
    uri: "http://localhost:44300/"
};

And here is login.js:

import settings from "./settings.js";
import common from "./common.js";

window.onload = () => {
    "use strict";

    localStorage.removeItem("auth");

    function login() {
        const user = {
            "email": document.getElementById("email").value,
            "password": document.getElementById("password").value
        };

        common.post(settings.uri + "identity/login?d=frontend", (token) => {
            const auth = {
                "email": user.email,
                "token": token
            };
            localStorage.setItem("auth", JSON.stringify(auth));
            location.href = "/store.html";
        }, () => {
            alert("Wrong credentials.");
        }, user);
    };

    document.getElementById("login").onclick = () => {
        login();
    };

    document.getElementById("password").onkeyup = (e) => {
        if (e.key === 'Enter') {
            login();
        }
    };

    document.getElementById("register").onclick = () => {
        location.href = "/register.html";
    };
};

common.js contains functions for executing GET, POST and DELETE requests:

export default {
    post: async (url, callback, errorCallback, content, token) => {
        try {
            const headers = {
                "Content-Type": "application/json;charset=UTF-8"
            };
            if (token) {
                headers["Authorization"] = `Bearer ${token}`;
            }
            const response = await fetch(url, {
                method: "POST",
                headers,
                body: JSON.stringify(content)
            });
            if (response.ok) {
                const data = await response.text();
                if (callback) {
                    callback(data);
                }
            } else {
                if (errorCallback) {
                    errorCallback(response.status);
                }
            }
        } catch (err) {
            if (errorCallback) {
                errorCallback(err);
            }
        }
    },
    get: async (url, callback, errorCallback, token) => {
        try {
            const headers = {
                "Content-Type": "application/json;charset=UTF-8"
            };
            if (token) {
                headers["Authorization"] = `Bearer ${token}`;
            }
            const response = await fetch(url, {
                method: "GET",
                headers
            });
            if (response.ok) {
                const data = await response.text();

                if (callback) {
                    callback(data);
                }
            } else {
                if (errorCallback) {
                    errorCallback(response.status);
                }
            }
        } catch (err) {
            if (errorCallback) {
                errorCallback(err);
            }
        }
    },
    delete: async (url, callback, errorCallback, token) => {
        try {
            const headers = {
                "Content-Type": "application/json;charset=UTF-8"
            };
            if (token) {
                headers["Authorization"] = `Bearer ${token}`;
            }
            const response = await fetch(url, {
                method: "DELETE",
                headers
            });

            if (response.ok) {
                if (callback) {
                    callback();
                }
            } else {
                if (errorCallback) {
                    errorCallback(response.status);
                }
            }
        } catch (err) {
            if (errorCallback) {
                errorCallback(err);
            }
        }
    }
};

The other pages in the frontend and in the backend are done pretty much the same way.

In the frontend, there are four pages. A login page, a page for registering users, a page for accessing the store, and a page for accessing the cart.

The frontend allows registered users to see the available catalog items, add catalog items to the cart, and remove catalog items from the cart.

Here is a screenshot of the store page in the frontend:

In the backend, there are two pages. A login page and a page for managing the store.

The backend allows admin users to see the available catalog items, create new catalog items, update catalog items, and remove catalog items.

Here is a screenshot of the store page in the backend:

Unit Tests

In this section, we will be unit testing all the microservices using xUnit and Moq.

When unit testing controller logic, only the contents of a single action are tested, not the behavior of its dependencies or of the framework itself.

xUnit simplifies the testing process and allows us to spend more time focusing on writing our tests.

Moq is a popular and friendly mocking framework for .NET. We will be using it in order to mock repositories and middleware services.

To unit test catalog microservice, first a xUnit testing project CatalogMicroservice.UnitTests was created. Then, a unit testing class CatalogControllerTest was created. This class contains unit testing methods of the catalog controller.

A reference of the project CatalogMicroservice was added to CatalogMicroservice.UnitTests project.

Then, Moq was added using Nuget package manager. At this point, we can start focusing on writing our tests.

A reference of CatalogController was added to CatalogControllerTest:

private readonly CatalogController _controller;

Then, in the constructor of our unit test class, a mock repository was added as follows:

public CatalogControllerTest()
{
    var mockRepo = new Mock<ICatalogRepository>();
    mockRepo.Setup(repo => repo.GetCatalogItems()).Returns(_items);
    mockRepo.Setup(repo => repo.GetCatalogItem(It.IsAny<string>()))
        .Returns<string>(id => _items.FirstOrDefault(i => i.Id == id));
    mockRepo.Setup(repo => repo.InsertCatalogItem(It.IsAny<CatalogItem>()))
        .Callback<CatalogItem>(_items.Add);
    mockRepo.Setup(repo => repo.UpdateCatalogItem(It.IsAny<CatalogItem>()))
        .Callback<CatalogItem>(i =>
        {
            var item = _items.FirstOrDefault(catalogItem => catalogItem.Id == i.Id);
            if (item != null)
            {
                item.Name = i.Name;
                item.Description = i.Description;
                item.Price = i.Price;
            }
        });
    mockRepo.Setup(repo => repo.DeleteCatalogItem(It.IsAny<string>()))
        .Callback<string>(id => _items.RemoveAll(i => i.Id == id));
    _controller = new CatalogController(mockRepo.Object);
}

where _items is a list of CatalogItem:

private static readonly string A54Id = "653e4410614d711b7fc953a7";
private static readonly string A14Id = "253e4410614d711b7fc953a7";
private readonly List<CatalogItem> _items = new()
{
    new()
    {
        Id = A54Id,
        Name = "Samsung Galaxy A54 5G",
        Description = "Samsung Galaxy A54 5G mobile phone",
        Price = 500
    },
    new()
    {
        Id = A14Id,
        Name = "Samsung Galaxy A14 5G",
        Description = "Samsung Galaxy A14 5G mobile phone",
        Price = 200
    }
};

Then, here is the test of GET api/catalog:

[Fact]
public void GetCatalogItemsTest()
{
    var okObjectResult = _controller.Get();
    var okResult = Assert.IsType<OkObjectResult>(okObjectResult);
    var items = Assert.IsType<List<CatalogItem>>(okResult.Value);
    Assert.Equal(2, items.Count);
}

Here is the test of GET api/catalog/{id}:

[Fact]
public void GetCatalogItemTest()
{
    var id = A54Id;
    var okObjectResult = _controller.Get(id);
    var okResult = Assert.IsType<OkObjectResult>(okObjectResult);
    var item = Assert.IsType<CatalogItem>(okResult.Value);
    Assert.Equal(id, item.Id);
}

Here is the test of POST api/calatlog:

[Fact]
public void InsertCatalogItemTest()
{
    var createdResponse = _controller.Post(
        new CatalogItem
        {
            Id = "353e4410614d711b7fc953a7",
            Name = "iPhone 15",
            Description = "iPhone 15 mobile phone",
            Price = 1500
        }
    );
    var response = Assert.IsType<CreatedAtActionResult>(createdResponse);
    var item = Assert.IsType<CatalogItem>(response.Value);
    Assert.Equal("iPhone 15", item.Name);
}

Here is the test of PUT api/catalog:

[Fact]
public void UpdateCatalogItemTest()
{
    var id = A54Id;
    var okObjectResult = _controller.Put(
        new CatalogItem
        {
            Id = id,
            Name = "Samsung Galaxy S23 Ultra",
            Description = "Samsung Galaxy S23 Ultra mobile phone",
            Price = 1500
        });
    Assert.IsType<OkResult>(okObjectResult);
    var item = _items.FirstOrDefault(i => i.Id == id);
    Assert.NotNull(item);
    Assert.Equal("Samsung Galaxy S23 Ultra", item.Name);
    okObjectResult = _controller.Put(null);
    Assert.IsType<NoContentResult>(okObjectResult);
}

Here is the test of DELETE api/catalog/{id}:

[Fact]
public void DeleteCatalogItemTest()
{
    var id = A54Id;
    var item = _items.FirstOrDefault(i => i.Id == id);
    Assert.NotNull(item);
    var okObjectResult = _controller.Delete(id);
    Assert.IsType<OkResult>(okObjectResult);
    item = _items.FirstOrDefault(i => i.Id == id);
    Assert.Null(item);
}

Unit tests of cart microservice and identity microservice were written in the same way.

Here are the unit tests of cart microservice:

public class CartControllerTest
{
    private readonly CartController _controller;
    private static readonly string UserId = "653e43b8c76b6b56a720803e";
    private static readonly string A54Id = "653e4410614d711b7fc953a7";
    private static readonly string A14Id = "253e4410614d711b7fc953a7";
    private readonly Dictionary<string, List<CartItem>> _carts = new()
    {
        {
            UserId,
            new()
            {
                new()
                {
                    CatalogItemId = A54Id,
                    Name = "Samsung Galaxy A54 5G",
                    Price = 500,
                    Quantity = 1
                },
                new()
                {
                    CatalogItemId = A14Id,
                    Name = "Samsung Galaxy A14 5G",
                    Price = 200,
                    Quantity = 2
                }
            }
        }
    };

    public CartControllerTest()
    {
        var mockRepo = new Mock<ICartRepository>();
        mockRepo.Setup(repo => repo.GetCartItems(It.IsAny<string>()))
            .Returns<string>(id => _carts[id]);
        mockRepo.Setup(repo => repo.InsertCartItem(It.IsAny<string>(), 
                               It.IsAny<CartItem>()))
            .Callback<string, CartItem>((userId, item) =>
            {
                if (_carts.TryGetValue(userId, out var items))
                {
                    items.Add(item);
                }
                else
                {
                    _carts.Add(userId, new List<CartItem> { item });
                }
            });
        mockRepo.Setup(repo => repo.UpdateCartItem(It.IsAny<string>(), 
                               It.IsAny<CartItem>()))
            .Callback<string, CartItem>((userId, item) =>
            {
                if (_carts.TryGetValue(userId, out var items))
                {
                    var currentItem = items.FirstOrDefault
                        (i => i.CatalogItemId == item.CatalogItemId);
                    if (currentItem != null)
                    {
                        currentItem.Name = item.Name;
                        currentItem.Price = item.Price;
                        currentItem.Quantity = item.Quantity;
                    }
                }
            });
        mockRepo.Setup(repo => repo.UpdateCatalogItem
                 (It.IsAny<string>(), It.IsAny<string>(), It.IsAny<decimal>()))
            .Callback<string, string, decimal>((catalogItemId, name, price) =>
            {
                var cartItems = _carts
                .Values
                .Where(items => items.Any(i => i.CatalogItemId == catalogItemId))
                .SelectMany(items => items)
                .ToList();

                foreach (var cartItem in cartItems)
                {
                    cartItem.Name = name;
                    cartItem.Price = price;
                }
            });
        mockRepo.Setup(repo => repo.DeleteCartItem
                      (It.IsAny<string>(), It.IsAny<string>()))
            .Callback<string, string>((userId, catalogItemId) =>
            {
                if (_carts.TryGetValue(userId, out var items))
                {
                    items.RemoveAll(i => i.CatalogItemId == catalogItemId);
                }
            });
        mockRepo.Setup(repo => repo.DeleteCatalogItem(It.IsAny<string>()))
            .Callback<string>((catalogItemId) =>
            {
                foreach (var cart in _carts)
                {
                    cart.Value.RemoveAll(i => i.CatalogItemId == catalogItemId);
                }
            });
        _controller = new CartController(mockRepo.Object);
    }

    [Fact]
    public void GetCartItemsTest()
    {
        var okObjectResult = _controller.Get(UserId);
        var okResult = Assert.IsType<OkObjectResult>(okObjectResult);
        var items = Assert.IsType<List<CartItem>>(okResult.Value);
        Assert.Equal(2, items.Count);
    }

    [Fact]
    public void InsertCartItemTest()
    {
        var okObjectResult = _controller.Post(
            UserId,
            new CartItem
            {
                CatalogItemId = A54Id,
                Name = "Samsung Galaxy A54 5G",
                Price = 500,
                Quantity = 1
            }
        );
        Assert.IsType<OkResult>(okObjectResult);
        Assert.NotNull(_carts[UserId].FirstOrDefault(i => i.CatalogItemId == A54Id));
    }

    [Fact]
    public void UpdateCartItemTest()
    {
        var catalogItemId = A54Id;
        var okObjectResult = _controller.Put(
            UserId,
            new CartItem
            {
                CatalogItemId = A54Id,
                Name = "Samsung Galaxy A54",
                Price = 550,
                Quantity = 2
            }
        );
        Assert.IsType<OkResult>(okObjectResult);
        var catalogItem = _carts[UserId].FirstOrDefault
                          (i => i.CatalogItemId == catalogItemId);
        Assert.NotNull(catalogItem);
        Assert.Equal("Samsung Galaxy A54", catalogItem.Name);
        Assert.Equal(550, catalogItem.Price);
        Assert.Equal(2, catalogItem.Quantity);
    }

    [Fact]
    public void DeleteCartItemTest()
    {
        var id = A14Id;
        var items = _carts[UserId];
        var item = items.FirstOrDefault(i => i.CatalogItemId == id);
        Assert.NotNull(item);
        var okObjectResult = _controller.Delete(UserId, id);
        Assert.IsType<OkResult>(okObjectResult);
        item = items.FirstOrDefault(i => i.CatalogItemId == id);
        Assert.Null(item);
    }

    [Fact]
    public void UpdateCatalogItemTest()
    {
        var catalogItemId = A54Id;
        var okObjectResult = _controller.Put(
            A54Id,
            "Samsung Galaxy A54",
            550
        );
        Assert.IsType<OkResult>(okObjectResult);
        var catalogItem = _carts[UserId].FirstOrDefault
                         (i => i.CatalogItemId == catalogItemId);
        Assert.NotNull(catalogItem);
        Assert.Equal("Samsung Galaxy A54", catalogItem.Name);
        Assert.Equal(550, catalogItem.Price);
        Assert.Equal(1, catalogItem.Quantity);
    }

    [Fact]
    public void DeleteCatalogItemTest()
    {
        var id = A14Id;
        var items = _carts[UserId];
        var item = items.FirstOrDefault(i => i.CatalogItemId == id);
        Assert.NotNull(item);
        var okObjectResult = _controller.Delete(id);
        Assert.IsType<OkResult>(okObjectResult);
        item = items.FirstOrDefault(i => i.CatalogItemId == id);
        Assert.Null(item);
    }
}

Here are the unit tests of identity microservice:

public class IdentityControllerTest
{
    private readonly IdentityController _controller;
    private static readonly string AdminUserId = "653e4410614d711b7fc951a7";
    private static readonly string FrontendUserId = "653e4410614d711b7fc952a7";
    private static readonly User UnknownUser = new()
    {
        Id = "653e4410614d711b7fc957a7",
        Email = "unknown@store.com",
        Password = "4kg245EBBE+1IF20pKSBafiNhE/+WydWZo41cfThUqh7tz7+n7Yn9w==",
        Salt = "2lApH7EgXLHjYAvlmPIDAaQ5ypyXlH8PBVmOI+0zhMBu5HxZqIH7+w==",
        IsAdmin = false
    };
    private readonly List<User> _users = new()
    {
        new()
        {
            Id = AdminUserId,
            Email = "admin@store.com",
            Password = "Ukg255EBBE+1IF20pKSBafiNhE/+WydWZo41cfThUqh7tz7+n7Yn9w==",
            Salt = "4lApH7EgXLHjYAvlmPIDAaQ5ypyXlH8PBVmOI+0zhMBu5HxZqIH7+w==",
            IsAdmin = true
        },
        new()
        {
            Id = FrontendUserId,
            Email = "jdoe@store.com",
            Password = "Vhq8Klm83fCVILYhCzp2vKUJ/qSB+tmP/a9bD3leUnp1acBjS2I5jg==",
            Salt = "7+UwBowz/iv/sW7q+eYhJSfa6HiMQtJXyHuAShU+c1bUo6QUL4LIPA==",
            IsAdmin = false
        }
    };

    private static IConfiguration InitConfiguration()
    {
        var config = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .AddEnvironmentVariables()
            .Build();
        return config;
    }

    public IdentityControllerTest()
    {
        var mockRepo = new Mock<IUserRepository>();
        mockRepo.Setup(repo => repo.GetUser(It.IsAny<string>()))
            .Returns<string>(email => _users.FirstOrDefault(u => u.Email == email));
        mockRepo.Setup(repo => repo.InsertUser(It.IsAny<User>()))
            .Callback<User>(_users.Add);
        var configuration = InitConfiguration();
        var jwtSection = configuration.GetSection("jwt");
        var jwtOptions = Options.Create(new JwtOptions
        {
            Secret = jwtSection["secret"],
            ExpiryMinutes = int.Parse(jwtSection["expiryMinutes"] ?? "60")
        });
        _controller = new IdentityController
                      (mockRepo.Object, new JwtBuilder(jwtOptions), new Encryptor());
    }

    [Fact]
    public void LoginTest()
    {
        // User not found
        var notFoundObjectResult = _controller.Login(UnknownUser);
        Assert.IsType<NotFoundObjectResult>(notFoundObjectResult);

        // Backend failure
        var user = new User
        {
            Id = FrontendUserId,
            Email = "jdoe@store.com",
            Password = "aaaaaa",
            IsAdmin = false
        };
        var badRequestObjectResult = _controller.Login(user, "backend");
        Assert.IsType<BadRequestObjectResult>(badRequestObjectResult);

        // Wrong password
        user.Password = "bbbbbb";
        badRequestObjectResult = _controller.Login(user);
        Assert.IsType<BadRequestObjectResult>(badRequestObjectResult);

        // Frontend success
        user.Password = "aaaaaa";
        var okObjectResult = _controller.Login(user);
        var okResult = Assert.IsType<OkObjectResult>(okObjectResult);
        var token = Assert.IsType<string>(okResult.Value);
        Assert.NotEmpty(token);

        // Backend success
        var adminUser = new User
        {
            Id = AdminUserId,
            Email = "admin@store.com",
            Password = "aaaaaa",
            IsAdmin = true
        };
        okObjectResult = _controller.Login(adminUser, "backend");
        okResult = Assert.IsType<OkObjectResult>(okObjectResult);
        token = Assert.IsType<string>(okResult.Value);
        Assert.NotEmpty(token);
    }

    [Fact]
    public void RegisterTest()
    {
        // Failure (user already exists)
        var user = new User
        {
            Id = FrontendUserId,
            Email = "jdoe@store.com",
            Password = "aaaaaa",
            IsAdmin = false
        };
        var badRequestObjectResult = _controller.Register(user);
        Assert.IsType<BadRequestObjectResult>(badRequestObjectResult);

        // Success (new user)
        user = new User
        {
            Id ="145e4410614d711b7fc952a7",
            Email = "ctaylor@store.com",
            Password = "cccccc",
            IsAdmin = false
        };
        var okResult = _controller.Register(user);
        Assert.IsType<OkResult>(okResult);
        Assert.NotNull(_users.FirstOrDefault(u => u.Id == user.Id));
    }

    [Fact]
    public void ValidateTest()
    {
        // User not found
        var notFoundObjectResult = _controller.Validate(UnknownUser.Email, string.Empty);
        Assert.IsType<NotFoundObjectResult>(notFoundObjectResult);

        // Invalid token
        var badRequestObjectResult = _controller.Validate("jdoe@store.com", "zzz");
        Assert.IsType<BadRequestObjectResult>(badRequestObjectResult);

        // Success
        var user = new User
        {
            Id = FrontendUserId,
            Email = "jdoe@store.com",
            Password = "aaaaaa",
            IsAdmin = false
        };
        var okObjectResult = _controller.Login(user);
        var okResult = Assert.IsType<OkObjectResult>(okObjectResult);
        var token = Assert.IsType<string>(okResult.Value);
        Assert.NotEmpty(token);
        okObjectResult = _controller.Validate(user.Email, token);
        okResult = Assert.IsType<OkObjectResult>(okObjectResult);
        var userId = Assert.IsType<string>(okResult.Value);
        Assert.Equal(user.Id, userId);
    }
}

If we run the unit tests, we will notice that they all pass:

You can find unit test results on GitHub Actions.

Monitoring using Health Checks

In this section, we will see how to add health checks to catalog microservice for monitoring purposes.

Health checks are endpoints provided by a service to check whether the service is running properly.

Heath checks are used to monitor services such as:

Database (SQL Server, Oracle, MySql, MongoDB, etc.)
External API connectivity
Disk connectivity (read/write)
Cache service (Redis, Memcached, etc.)

If you don't find an implementation that suits you, you can create your own custom implementation.

To add health checks to catalog microservice, the following nuget packages were added:

AspNetCore.HealthChecks.MongoDb
AspNetCore.HealthChecks.UI
AspNetCore.HealthChecks.UI.Client
AspNetCore.HealthChecks.UI.InMemory.Storage

AspNetCore.HealthChecks.MongoDb package is used to check the health of MongoDB.

AspNetCore.HealthChecks.UI packages are used to use health check UI that stores and shows the health checks results from the configured HealthChecks uris.

Then, ConfigureServices method in Startup.cs was updated as follows:

services.AddHealthChecks()
    .AddMongoDb(
        mongodbConnectionString: (
            Configuration.GetSection("mongo").Get<MongoOptions>()
            ?? throw new Exception("mongo configuration section not found")
        ).ConnectionString,
        name: "mongo",
        failureStatus: HealthStatus.Unhealthy
    );
services.AddHealthChecksUI().AddInMemoryStorage();

And Configure method in Startup.cs was updated as follows:

app.UseHealthChecks("/healthz", new HealthCheckOptions
{
    Predicate = _ => true,
    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
});

app.UseHealthChecksUI();

Finally, appsettings.json was updated as follows:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "mongo": {
    "connectionString": "mongodb://127.0.0.1:27017",
    "database": "store-catalog"
  },
  "jwt": {
    "secret": "9095a623-a23a-481a-aa0c-e0ad96edc103",
    "expiryMinutes": 60
  },
  "HealthChecksUI": {
    "HealthChecks": [
      {
        "Name": "HTTP-Api-Basic",
        "Uri": "http://localhost:44397/healthz"
      }
    ],
    "EvaluationTimeOnSeconds": 10,
    "MinimumSecondsBetweenFailureNotifications": 60
  }
}

If we run catalog microservice, we will get the following UI when accessing http://localhost:44326/healthchecks-ui:

That's it. Health checks of other microservices and gateways were implemented in the same way.

How to Run the Application

To run the application, open the solution store.sln in Visual Studio 2022 as administrator.

You will need to install MongoDB if it is not installed.

First, right click on the solution, click on properties and select multiple startup projects. Select all the projects as startup projects except Middleware and unit tests projects.

Then, press F5 to run the application.

You can access the frontend from http://localhost:44317/.

You can access the backend from http://localhost:44301/.

To login to the frontend for the first time, just click on Register to create a new user and login.

To login to the backend for the first time, you will need to create an admin user. To do so, open Swagger through http://localhost:44397/ and register or open Postman and execute the following POST request http://localhost:44397/api/identity/register with the following payload:

{
  "email": "admin@store.com",
  "password": "pass",
  "isAdmin": true
}

Finally, you can login to the backend with the admin user you created.

If you want to modify MongoDB connection string, you need to update appsettings.json of microservices and gateways.

Below are all the endpoints:

Frontend: http://localhost:44317/
Backend: http://localhost:44301/
Frontend gateway: http://localhost:44300/
Backend gateway: http://localhost:44359/
Identity microservice: http://localhost:44397/
Catalog microservice: http://localhost:44326/
Cart microservice: http://localhost:44388/

How to Deploy the Application

You can deploy the application using Docker.

You will need to install Docker it is not installed.

First, copy the source code to a folder on your machine.

Then open a terminal, go to that folder (where store.sln file is located) and run the following command:

docker-compose up

That's it, the application will be deployed and will run.

Then, you can access the frontend from http://:44317/ and the backend from http://:44301/.

Here is a screenshot of the application running on Ubuntu:

For those who want to understand how the deployment is done, here is docker-compose.yml:

version: "3.8"
services:
  mongo:
    image: mongo
    ports:
       - 27017:27017

  catalog:
    build:
      context: .
      dockerfile: src/microservices/CatalogMicroservice/Dockerfile
    depends_on:
      - mongo
    ports:
      - 44326:80

  cart:
    build:
      context: .
      dockerfile: src/microservices/CartMicroservice/Dockerfile
    depends_on:
      - mongo
    ports:
      - 44388:80

  identity:
    build:
      context: .
      dockerfile: src/microservices/IdentityMicroservice/Dockerfile
    depends_on:
      - mongo
    ports:
      - 44397:80

  frontendgw:
    build:
      context: .
      dockerfile: src/gateways/FrontendGateway/Dockerfile
    depends_on:
      - mongo
      - catalog
      - cart
      - identity
    ports:
      - 44300:80

  backendgw:
    build:
      context: .
      dockerfile: src/gateways/BackendGateway/Dockerfile
    depends_on:
      - mongo
      - catalog
      - identity
    ports:
      - 44359:80

  frontend:
    build:
      context: .
      dockerfile: src/uis/Frontend/Dockerfile
    ports:
      - 44317:80

  backend:
    build:
      context: .
      dockerfile: src/uis/Backend/Dockerfile
    ports:
      - 44301:80

Then, appsettings.Production.json was used in microservices and gateways, and ocelot.Production.json was used in gateways.

For example, here is appsettings.Production.json of catalog microservice:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "mongo": {
    "connectionString": "mongodb://mongo",
    "database": "store-catalog"
  },
  "HealthChecksUI": {
    "HealthChecks": [
      {
        "Name": "HTTP-Api-Basic",
        "Uri": "http://catalog/healthz"
      }
    ],
    "EvaluationTimeOnSeconds": 10,
    "MinimumSecondsBetweenFailureNotifications": 60
  }
}

Here is Dockerfile of catalog microservice:

# syntax=docker/dockerfile:1

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["src/microservices/CatalogMicroservice/CatalogMicroservice.csproj", 
      "microservices/CatalogMicroservice/"]
COPY src/middlewares middlewares/
RUN dotnet restore "microservices/CatalogMicroservice/CatalogMicroservice.csproj"

WORKDIR "/src/microservices/CatalogMicroservice"
COPY src/microservices/CatalogMicroservice .
RUN dotnet build "CatalogMicroservice.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "CatalogMicroservice.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
ENV ASPNETCORE_URLS=http://+:80
EXPOSE 80
EXPOSE 443
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "CatalogMicroservice.dll"]

Multistage build is explained here. It helps make the process of building containers more efficient, and makes containers smaller by allowing them to contain only the bits that your app needs at run time.

Here is ocelot.Production.json of the frontend gateway:

{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/catalog",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "catalog",
          "Port": 80
        }
      ],
      "UpstreamPathTemplate": "/catalog",
      "UpstreamHttpMethod": [ "GET" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    },
    {
      "DownstreamPathTemplate": "/api/catalog/{id}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "catalog",
          "Port": 80
        }
      ],
      "UpstreamPathTemplate": "/catalog/{id}",
      "UpstreamHttpMethod": [ "GET" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    },
    {
      "DownstreamPathTemplate": "/api/cart",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "cart",
          "Port": 80
        }
      ],
      "UpstreamPathTemplate": "/cart",
      "UpstreamHttpMethod": [ "GET" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    },
    {
      "DownstreamPathTemplate": "/api/cart",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "cart",
          "Port": 80
        }
      ],
      "UpstreamPathTemplate": "/cart",
      "UpstreamHttpMethod": [ "POST" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    },
    {
      "DownstreamPathTemplate": "/api/cart",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "cart",
          "Port": 80
        }
      ],
      "UpstreamPathTemplate": "/cart",
      "UpstreamHttpMethod": [ "PUT" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    },
    {
      "DownstreamPathTemplate": "/api/cart",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "cart",
          "Port": 80
        }
      ],
      "UpstreamPathTemplate": "/cart",
      "UpstreamHttpMethod": [ "DELETE" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      }
    },
    {
      "DownstreamPathTemplate": "/api/identity/login",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "identity",
          "Port": 80
        }
      ],
      "UpstreamPathTemplate": "/identity/login",
      "UpstreamHttpMethod": [ "POST" ]
    },
    {
      "DownstreamPathTemplate": "/api/identity/register",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "identity",
          "Port": 80
        }
      ],
      "UpstreamPathTemplate": "/identity/register",
      "UpstreamHttpMethod": [ "POST" ]
    },
    {
      "DownstreamPathTemplate": "/api/identity/validate",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "identity",
          "Port": 80
        }
      ],
      "UpstreamPathTemplate": "/identity/validate",
      "UpstreamHttpMethod": [ "GET" ]
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "http://localhost:44300/"
  }
}

Here is appsettings.Production.json of the frontend gateway:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "jwt": {
    "secret": "9095a623-a23a-481a-aa0c-e0ad96edc103"
  },
  "mongo": {
    "connectionString": "mongodb://mongo"
  },
  "HealthChecksUI": {
    "HealthChecks": [
      {
        "Name": "HTTP-Api-Basic",
        "Uri": "http://frontendgw/healthz"
      }
    ],
    "EvaluationTimeOnSeconds": 10,
    "MinimumSecondsBetweenFailureNotifications": 60
  }
}

And finally, here is Dockerfile of the frontend gateway:

# syntax=docker/dockerfile:1

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["src/gateways/FrontendGateway/FrontendGateway.csproj", "gateways/FrontendGateway/"]
COPY src/middlewares middlewares/
RUN dotnet restore "gateways/FrontendGateway/FrontendGateway.csproj"

WORKDIR "/src/gateways/FrontendGateway"
COPY src/gateways/FrontendGateway .
RUN dotnet build "FrontendGateway.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "FrontendGateway.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
ENV ASPNETCORE_URLS=http://+:80
EXPOSE 80
EXPOSE 443
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "FrontendGateway.dll"]

The configurations of other microservices and the backend gateway are done in pretty much the same way.

That's it! I hope you enjoyed reading this article.

References

Build Your Own nodemon in Few Lines of Code

aelassas — Sat, 19 Oct 2024 14:26:50 +0000

Introduction
Setting up the Project
Server
Watcher
Bringing the Pieces Together
References

You can find source code here: https://github.com/aelassas/watcher

Introduction

When working on Node.js applications, you often need to restart your server after some changes. Well, this would be annoying if you have to manually restart your server each time you do some modifications in your source code. Thankfully, there are some utilities available that let you automatically restart your server when changes are detected. And the most famous one is nodemon. nodemon is a tool that helps develop Node.js based applications by automatically restarting the node application when file changes in the directory are detected. The purpose of this tip is not to reinvent the wheel, but to show you how you can create your own utility that monitors for any changes in your Node.js application and automatically restart the server in just a few lines of code.

Setting up the Project

The first step will be to initialize our Node.js project:

npm init

Then, we will have to update package.json in order to add support of ES6 by setting module as type:

{
  "name": "watcher",
  "type": "module",
  "version": "1.0.0",
  "author": "Akram El Assas"
}

Then, we will install development dependencies:

npm i -D @types/node

@types/node: To have autocomplete in Visual Studio Code

Server

We will create a simple web server server.js as follows:

import { createServer } from 'http'

const PORT = 8888

createServer((_, res) => {
    res.writeHead(200, { 'Content-Type': 'text/plain' })
    res.write('Hello World!')
    res.end()
}).listen(PORT)

console.log('HTTP server is running on Port', PORT)

Then, we will create a watcher in order to restart the server each time changes are detected on the parent folder of the server and in its subfolders through the following command:

node watcher.js server.js

Watcher

The watcher will restart the server each time changes are detected.

First and foremost, we'll need to retrieve the command-line arguments. In Node.js, we can have access to command-line arguments through process.argv. The process.argv property returns an array containing the command-line arguments passed when the Node.js process was launched. The first element will be execPath. The second element will be the path to the JavaScript file being executed. The remaining elements will be any additional command-line arguments.

If we run the following command:

node watcher.js server.js

process.argv will be as follows:

[
  'C:\\Program Files\\nodejs\\node.exe',
  'C:\\dev\\watcher\\src\\watcher.js',
  'server.js'
]

The first element is the path to Node.js executable. The second element is the path to watcher.js. And the last element is server.js. Thus, we can start our code by declaring the first and third elements as follows:

const [node, _, file] = process.argv

We then need to create a function that starts a child process that launches Node.js with the specified file as argument which in our case is server.js. To do so, we will use spawn method from child_process module. The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. The advantages of using spawn method is that we can redirect stdout and stderr of the child process to the parent process using pipe method. pipe method is used to attach a writable stream to a readable stream so that it consequently switches into flowing mode and then pushes all the data that it has to the attached writable stream. The source code of our function will look like follows:

import { spawn } from 'child_process'

const [node, _, file] = process.argv

const spawnNode = () => {
    const childProcess = spawn(node, [file])
    childProcess.stdout.pipe(process.stdout)
    childProcess.stderr.pipe(process.stderr)

    childProcess.on('close', (code) => {
        if (code !== null) {
            process.exit(code)
        }
    })

    return childProcess
}

First of all, we spawn a child Node.js process with the given file argument. Then, we redirect stdout and stderr of the child process to the parent process using pipe method. Then, when the child process is closed, we exit the parent process with the same exit code. The process.exit() method instructs Node.js to terminate the process synchronously with an exit status of code. If code is omitted, exit uses either the success code 0 or the value of process.exitCode if it has been set. Node.js will not terminate until all the exit event listeners are called. And finally, we return the child process.

Now, we need to detect changes on the parent folder of the file and its subfolders. And each time a change related to a JavaScript file is detected, we will kill the child process and spawn the child process again. To do so, we will use watch method from fs/promises module. The fs/promises.watch() method returns an async iterator that watches for changes on filename, where filename is either a file or a directory. We will create a watcher on the parent folder of the file. Then, we will iterate through watcher. We will ignore node_modules folder and each time a change is detected on a JavaScript file, we will kill the child process and spawn it again as follows:

let childProcess = spawnNode()
const watcher = watch(dirname(file), { recursive: true })
for await (const event of watcher) {
    if (
        !event.filename.includes('node_modules') &&
        event.filename.endsWith('.js')
    ) {
        childProcess.kill('SIGKILL')
        childProcess = spawnNode()
    }
}

The subprocess.kill() method sends a signal to the child process. If no argument is given, the process will be sent the SIGTERM signal. SIGKILL signal cannot be caught, blocked, or ignored and forces the child process to stop. See signal(7) for a list of available signals.

That's it! We have finished our own nodemon in just a few lines of code.

Last but not least, we need to add the start and dev scripts to our package.json as follows:

{
  "name": "watcher",
  "type": "module",
  "version": "1.0.0",
  "scripts": {
    "start": "node server.js",
    "dev": "node watcher.js server.js"
  },
  "author": "Akram El Assas",
  "devDependencies": {
    "@types/node": "^18.11.17"
  }
}

In order to start our application, just type the following command:

npm run dev

Now if we run our application and make changes to server.js, the server will be restarted automatically. We no longer need to stop and start the server manually.

Bringing the Pieces Together

We set up our own nodemon in just a few lines of code. Now, The whole source code of our watcher.js looks like follows:

import { spawn } from 'child_process'
import { watch } from 'fs/promises'
import { dirname } from 'path'

const [node, _, file] = process.argv

const spawnNode = () => {
    const childProcess = spawn(node, [file])
    childProcess.stdout.pipe(process.stdout)
    childProcess.stderr.pipe(process.stderr)

    childProcess.on('close', (code) => {
        if (code !== null) {
            process.exit(code)
        }
    })

    return childProcess
}

let childProcess = spawnNode()
const watcher = watch(dirname(file), { recursive: true })
for await (const event of watcher) {
    if (
        !event.filename.includes('node_modules') &&
        event.filename.endsWith('.js')
    ) {
        childProcess.kill('SIGKILL')
        childProcess = spawnNode()
    }
}

This is just a simple example but you can imagine other situations where you monitor changes on video files and each time a change is detected, a conversion child process (ffmpeg) is launched.

You can also implement other options such as:

Ignoring specific files or directories
Watching specific directories
Monitoring multiple directories
Specifying extension watch list
Delaying restarting
Running executables other than Node.js such as Python, Ruby, make, etc.
and so on...

Forem: aelassas

Servy vs. NSSM vs. WinSW

The Contenders

Why the Wrapper Matters

The Comparison: Feature Breakdown

The Servy Advantage

Conclusion

From Zero to Storefront: My Journey Building a Property Rental Platform

Contents

Frontend

Admin Dashboard

Functional Programming in C#

Contents

Empty Set

Set All

Singleton Set

Other Sets

Even numbers

Odd Numbers

Multiples of 3

Multiples of 5

Prime Numbers

Union

Intersection

Cartesian Product

Complements

Symmetric Difference

Other Operations

Contains

Add

Remove

Translate

Homothety

Rotate

From Zero to Storefront: My Journey Building a Car Rental Website and Mobile App

Contents

Frontend

Admin Dashboard

From Zero to Storefront: My Journey Building an E-commerce Site

Contents

Frontend

Admin Dashboard

Test-Driven Development: A Comprehensive Guide

Contents

Empty Translator Name

No Translation

File with only Translator Name

One Translation

Multiple Translations

Wrong File

Empty Translator Name

No Translation

Translator Name

One Translation

Multiple Translations

Wrong File

Empty File

Files with only Translator Names

Files with Translations

Wrong File

Build Workflow

Test Worfklow

Functional Programming in TypeScript

Contents

Empty set

Set All

Singleton Set

Other Sets

Even Numbers

Odd Numbers

Multiples of 3

Multiples of 5

Prime Numbers

Union

Intersection

Cartesian Product

Complements

Symmetric Difference

Other Operations

Contains