DEV Community: Ibrahim Ayuba

Building a Scalable REST API with TypeScript, Express, Drizzle ORM, and Turso Database: A Step-by-Step Guide

Ibrahim Ayuba — Mon, 27 May 2024 13:57:44 +0000

Building REST APIs with Express.js is straightforward and a must-have skill for every web developer. In this guide, we'll learn a step-by-step approach to building a REST API. We'll use the following technologies to build an API for a note-taking application:

TypeScript: Literally JavaScript with static typing. It compiles down to JavaScript. Suitable for building large-scale JavaScript applications with confidence.
Express: A minimalist, unopinionated Node.js framework for building server-side applications.
Drizzle: An SQL Object-Relational Mapping (ORM) tool that makes it easy to interact with the database.
Turso: A fast and scalable SQLite database technology for building production-ready applications. Easy to set up and has a generous free tier.

Why Learn Express?

Using opinionated Node.js frameworks such as Nest.js and Sails.js is great, especially for large-scale applications. However, they're not ideal for beginners because they abstract away a lot of how the server actually works. In fact, Nest.js is an abstraction on top of Express.js.

Express.js, on the other hand, is unopinionated and allows for more flexibility and a better learning experience. It's lightweight and easy to get started with, especially if you're coming from frontend JavaScript. Moreover, understanding Express will give you the knowledge and confidence to pick up other Node.js backend frameworks.

What the Guide Covers

We will cover the following topics in this article:

How to set up a TypeScript Project with Express
How Express middlewares work
Setting up Turso database
Connecting and interacting with Turso database using Drizzle ORM
Creating a CRUD (Create Read Update Update Delete) API
How to validate and sanitize data using the third-party express-validator middlewares
Testing an API with Thunder Client VS Code extension

Prerequisites

To effortlessly follow this tutorial, you should have a basic understanding of the following:

JavaScript (We will be using TypeScript, but JavaScript knowledge is enough to follow this guide)
Node.js
Structure Query Language (SQL)
How a server works

Let's begin!

Setting Up A TypeScript Project with Express

The first steps to building a REST API with Express.js and TypeScript are:

Generating and configuring package.json
Installing basic dependencies necessary to initially run our app
Generating and configuring tsconfig.json

1. Generating and configuring `package.json` file



npm init -y

This command generates a package.json file in the root directory.
Next, update the file to look like this:



{
  "name": "article",
  "version": "1.0.0",
  "main": "dist/index.js",
  "type": "module",
  "scripts": {
    "dev": "node --loader=ts-node/esm --env-file=.env --watch src/index.ts",
    "build": "npx tsc",
    "start": "node --env-file=.env dist/index.js"
  },
  ...
}

The main option in the above package.json file points to the destination of the JavaScript file after compilation. The dist/index.js file will be generated (usually for production) when you execute the build script command by running npm run build on the terminal. The start command is used to start the server in production.

The dev script command is used to run the application in development mode. It contains the following commands:

node: Uses the Node runtime to execute the code.
--loader=ts-node/esm: Uses the ts-node package (we'll later install) to compile our code to JavaScript during development.
--env-file=.env: Tells Node where the .env file is located.
-watch: Reruns our code whenever we make an update, enabling automatic reloading during development.

2. Installing starter dependencies

We'll install some packages needed to kickstart our application. Aside from typescript and express, we will install the following packages:

ts-node: A package that compiles our TypeScript code to JavaScript during development, allowing us to run our application without the need for explicit compilation.
@types/express: A package that provides type definitions for Express.js, helping TypeScript to recognize and understand the types and interfaces of Express.js, enabling better code completion, error reporting, and overall development experience.



npm i express; npm i -D typescript ts-node @types/express

The -D flag, short for --save-dev, indicates that the packages being installed are development dependencies, meaning they are only required for development purposes and will not be needed in production. By using the -D flag, we are telling npm to include these packages in the devDependencies section of our package.json file, rather than the dependencies section, which is used for production dependencies.

3. Generating and configuring `tsconfig.json`

The following command generates the tsconfig.json file in the root directory:



npx tsc --init

The generated tsconfig.json file will contain many commented out TypeScript compiler options. Uncomment out the following options and update them accordingly:



{
  "compilerOptions": {
    ....

    "module": "NodeNext",
    "rootDir": "./src",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    ....
  }
}

Recommended starter file structure for the project

Create the necessary folders and files
Your file structure should look like this:



├── .env
├── .gitignore
├── package-lock.json
├── package.json
├── src
│   ├── db
│   ├── handlers  
│   ├── routes
│   ├── lib
│   ├── middleware
│   ├── index.ts
│   └── server.ts
└── tsconfig.js

Express Middleware

We'll use middleware functions throughout the project. So, let's take some time to understand them. If you're already familiar with Express middleware, you can skip this section.

Without middleware

To best illustrate this concept, I made a little sketch using excalidraw:

Normally, this is how a client will communicate with a server. In this case, the client requests all the notes in the database. The server makes a request to the database and, depending on the database's response, returns the requested resources or an error.
This approach keeps the server open for all kinds of requests. As API developers, we want to ensure that the client is requesting the right way and is not a malicious actor. So, we introduce middleware into the equation:

With middleware

The middleware sits between the client's request and the server's handler function. Whenever the server receives a request from the client, the request has to pass through the middleware and gets securitized in the process. In the above sketch, the middleware modified the request object. Express middleware can do more, including the following:

Execute any code
Terminate the request
Make changes to the request or response object
Detect errors
Authentication and authorization

How to define an express middleware



import express, {Request, Response, NextFunction} from "express"
const app = express()

const logRequestMethod = (req: Request, res: Response, next: NextFunction) => {
    console.log(req.method)
    next()
}
const logHostname = (req: Request, res: Response, next: NextFunction) => {
    console.log(req.hostname)
    next()
}

logRequestMethod and logHostname are middlewares responsible for logging the request's HTTP method and hostname respectively. Typically, an Express middleware has three arguments:

request
response
next

If we don't call the next() function, respond back to the client, or terminate the request, the server will hang in the middleware. The next() function transfers control to the next middleware or handler.

How to use an express middleware

Basically, there are two ways of using an Express middleware:

On an application level: An application-level middleware will execute whenever a request reaches the server and not terminated by other middleware before it. We can invoke application-level middleware using app.use(middlewareFunction). For example, let's use the above logRequestMethod on the app level:



app.use(logRequestMethod)

Route-specific middleware: We can restrict a middleware to a particular route. This type of middleware will only execute when a request is made to that particular route. Note that whether we're using a middleware on the app or route level, we can have one or more of them separated by commas. For instance, let's use logRequestMethod and logHostname only when the client makes a request to the /about path:



app.get("/about", logRequestMethod, logHostname, (req, res) => {})

The app.use() can also take a path as the first argument and used for a route-specific middleware: app.use("/about", logRequestMethod).

Error middleware

Whenever a client request results in an unhandled error, Express.js has a default error middleware that sends the error message back to the client in HTML format. There are two common ways an error can go unhandled:

Not wrapping a code block that may result in an error in a try-catch
The client sending a request to a route that doesn't exist

We would create the following middlewares and use them on the application level to handle errors:

A custom error middleware that handles all errors and sends back an error response in JSON format to the client.
A not-found middleware that gets triggered whenever the client requests resources from a route that doesn't exist. This not-found middleware will forward an error message to the custom error middleware, which will send back an appropriate JSON response to the client.

Setting up the Error Middleware

As mentioned earlier, the next() function triggers a jump from the current middleware in execution to the next middleware or handler. However, if we pass an argument to the next() function, it jumps to the next error middleware on the stack. If we haven't defined a custom error middleware, it transfers control to Express's default error middleware.

Typically, you want to pass an Error object to the next() function. The issue with the inbuilt error class is that it only accepts one argument, which is the error message string. However, we want our error object to contain an error message and status code that we would use to send back the appropriate error message back to the client.

Let's create a child class of the error class and make it receive an extra statusCode argument. So, within the lib folder, create a custom-error.ts file and insert the following lines of code:

src/lib/custom-error.ts



export class CustomError extends Error {
  message: string;
  statusCode: number;
  constructor(message: string, statusCode: number) {
    super(message);
    this.statusCode = statusCode;
  }
}

Our CustomError class can form error objects with two arguments — the message and status code. We'll use CustomError throughout our code to forward errors that happen in our server to the error middleware we'll create in a moment.

Next, we'll create an error middleware that will receive the error object and form a proper JSON response for the client. Unlike the traditional middleware functions, error middleware takes four arguments — error, request, response, next.

Within the middleware folder, create error.ts file. Within, paste the following lines of code:

src/middleware/error.ts



import { Request, Response, NextFunction } from "express";
import { CustomError } from "../lib/custom-error.ts";

export function error(
  err: CustomError,
  req: Request,
  res: Response,
  next: NextFunction
) {
  try {
    const msg = JSON.parse(err.message);
    res.status(err.status).json({ msg });
  } catch (error) {
    res.status(err.status).json({ msg: err.message });
  }
}

The err argument is the same error that is passed into the next() function from some middleware or handler. The error middleware can handle both JSON strings and text strings.

By handling both JSON and text strings, our error middleware can flexibly accommodate different types of error messages, making it more robust and adaptable to various scenarios.

Setting up not-found middleware

We need to create a middleware that handles requests made to routes that do not exist. This is straightforward. Express executes all middleware in the stack except the request is terminated by some middleware. So, we'll simply create a middleware that forwards an error message to our error middleware and place it at the tail end of the middleware stack. At that position, it only gets hit when our Express app has scanned through all the routes we have defined and doesn't find any that matches the one the client is requesting.

Inside the middleware folder, create a not-found.ts file and paste the following lines of code:

src/middleware/not-found.ts



import { Response, Request, NextFunction } from "express";
import { CustomError } from "../lib/custom-error.ts";

export function notFound(req: Request, res: Response, next: NextFunction) {
  return next(new CustomError("Route not found", 404));
}

This not-found middleware creates a CustomError object with a 404 status code and passes it to the next error middleware using the next() function.

Setting up `server.ts` file

Let's set up the application server.ts file and implement the two middlewares we just created. Within the src folder, create the server.ts file:

src/server.ts



import express, { urlencoded, json } from "express";
import { notFound } from "./middleware/not-found.ts";
import { error } from "./middleware/error.ts";

const app = express();
app.use(urlencoded({ extended: true }));
app.use(json());

// ... other middlewares and routes ...

app.use(notFound);
app.use(error);

export default app;

The order of middleware matters in Express, and it's important to place the error middleware last, as it will catch any errors that occur in the previous middlewares or handlers. The not-found middleware should be placed just above the error middleware, as it will handle any requests that don't match any of the previous routes.

The urlencoded({ extended: true }) and json() middlewares are built-in Express middleware functions that parse requests with urlencoded and JSON payloads, respectively. They should be placed early in the middleware stack, as they need to parse the request body before any other middlewares or routes can handle the request.

Setting up the Turso Database and Drizzle ORM

On this section, we’ll learn how to set up and use Turso database and Drizzle ORM in the API.

How to set up a Turso database

To use Turso database, you need the connection URL and authentication token. Follow these steps to obtain the credentials:

Go to the Turso website
Click on the Sign Up button
Sign up with either Gmail or Github
Choose a username
Skip the "About you" form
Click on Create Database
Name your database (e.g., express-api-project)
Click on Create Database
Scroll down and click on Continue to Dashboard
In the dashboard's side menu, click on Databases
Click on the name of the database you created (e.g., express-api-project) at the base of the page
Scroll down, copy the URL, and click on the Generate Token button
Leave everything as it is and click on Generate Token
Copy the token
Paste the URL and token in your .env file as follows:



TURSO_AUTH_TOKEN=paste-token-here
TURSO_CONNECTION_URL=paste-url-here
PORT=3000

Installing necessary packages for our database



npm i @libsql/client drizzle-orm; npm i -D drizzle-kit

Create the Drizzle configuration file

After installing the necessary packages, create a drizzle.config.ts file in the root directory and paste the following configuration options:

drizzle.config.ts



import { defineConfig } from "drizzle-kit";

export default defineConfig({
  schema: "./src/db/schema.ts",
  out: "./src/db/migrations",
  driver: "turso",
  dbCredentials: {
    url: process.env.TURSO_CONNECTION_URL,
    authToken: process.env.TURSO_AUTH_TOKEN,
  },
  dialect: "sqlite",
  verbose: true,
  strict: true,
});

This file contains the configurations for drizzle ORM, including location of our schema and migrations. The verbose: true property prints out every action executed when making changes to the database. strict:true property ensures caution, forcing confirmation of any changes you want to make to the database.

Connect Turso database with Drizzle

Next, create the db.ts file in the db folder and paste the following lines of code:

src/db/db.ts



import { drizzle } from "drizzle-orm/libsql";
import { createClient } from "@libsql/client";
const client = createClient({
  url: process.env.TURSO_CONNECTION_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});
export const db = drizzle(client);

The drizzle(client) function establishes a connection between the database client and Drizzle ORM, enabling the use of the ORM’s capabilities to interact with the database.

Create Notes Schema and Migrations

Now that we have set up our database, let's create the notes schema, generate migrations, and apply the migrations to the Turso database.

Creating the notes schema

Let's define our schema file for the notes app project. In the db folder, create a new file named schema.ts and add the following code:

src/db/schema.ts



import { sqliteTable, integer, text } from "drizzle-orm/sqlite-core";

export const NotesTable = sqliteTable("note", {
  id: integer("id").primaryKey(),
  title: text("title").notNull(),
  body: text("body"),
});

This is similar to the CREATE TABLE statement in MySQL. It creates a table with the following columns:

id: A primary key that auto-increments, uniquely identifying each note
title: A text column that must not be null, representing the title of the note
body: A text column that can be null, representing the body or content of the note

Generating migrations

Next, we'll generate migrations using the following command in your terminal:



npx drizzle-kit generate

This command will create our database migrations in the "/src/db/migrations" directory, as specified in the drizzle.config.ts file.

Apply migrations

Next, apply the generated migrations to the Turso database by running the following command in your terminal:



npx drizzle-kit migrate

Creating Notes Router in a Modular Way

When building an API using Express, we can place all our routes directly on the Express app:



import express from "express";

const app = express();

//get request
app.get("/", handlerFunction1)

//post request
app.post("/add-something", handlerFunction2)

Using this approaching for small and demo applications is fine. But in large-scale projects, it can lead to a cluttered and hard-to-maintain codebase. Let’s see a better way.

Express Router function explained

Express.js provides the Router() function, which creates a router object. This object acts as a middleware, but with the added capability to attach HTTP methods (such as GET, POST, PUT, and DELETE) to it. This allows for modular and organized routing.

Here's an example of creating a simple router:



import { Router } from "express";

//defining the router
const routerObject = Router()

routerObject.get("/get-something", (req, res) => {})
routerObject.post("/post-something", (req, res) => {})
routerObject.delete("/delete-something", (req, res) => {})

//using the router in our app
app.use("/our-api", routerObject)

When a request URL starts with /our-api, the routerObject will be invoked, and the appropriate handler will be executed based on the HTTP method and the remaining part of the URL. For instance, if the request URL is /our-api/get-something, the GET handler attached to the /get-something route will be executed.

Creating the `notesRouter` object

The notes API will have the following endpoints:

API Endpoint	Method	Description
/add-note	POST	Add new note
/get-note/:id	GET	Get note with id
/get-all-notes	GET	Get all notes
/update-note/:id	PUT	Update note with id
/delete-note/:id	DELETE	Delete note with id

Within the routes folder, create notes.ts file and insert the following lines of code:

src/routes/notes.ts



import { Router } from "express";
import { addNote, deleteNote, getAllNotes, getNote, updateNote} from "../handlers/notes.ts";

const notesRouter = Router();

notesRouter.get("/get-note/:id", getNote);
notesRouter.get("/get-all-notes", getAllNotes);
notesRouter.post("/add-note", addNote);
notesRouter.put("/update-note/:id", updateNote);
notesRouter.delete("/delete-note/:id", deleteNote);

export default notesRouter;

Now that our notesRouter object is ready, let’s hook it to our app in our server.ts file:

src/server.ts



import express, { urlencoded, json } from "express";
import { notFound } from "./middleware/not-found.ts";
import { error } from "./middleware/error.ts";
import notesRouter from "./routes/notes.ts";

const app = express();
app.use(urlencoded({ extended: true }));
app.use(json());

app.use("/api", notesRouter);

app.use(notFound);
app.use(error);

export default app;

The URL to request any notes resource must start with /api. As we've seen, Express Router makes our application easier to manage and scale.

Next, we'll define our handlers, including addNote and getNote. Although we've imported them, we haven't created them yet.

Creating the Notes Handlers

Handlers are technically middlewares. Just like middleware functions, they have three arguments — request, response, and next. Typically, they respond to the client or send an error message to the error middleware using the next() function.

More importantly, we define the logic to interact with the database in the handlers. This is where Drizzle shines. Within the handlers folder, create a new file named notes.ts and add the following code:

src/handlers/notes.ts



import { eq } from "drizzle-orm";
import { db } from "../db/db.ts";
import { NotesTable } from "../db/schema.ts";
import { Response, Request, NextFunction } from "express";
import { CustomError } from "../lib/custom-error.ts";

export async function addNote(req: Request, res: Response, next: NextFunction) {
  try {
    const note = await db.insert(NotesTable).values(req.body).returning();
    res.status(201).json({ note });
  } catch (error) {
    next(new CustomError("Failed to add note", 500));
  }
}

export async function getAllNotes(req: Request,res: Response, next: NextFunction) {
  try {
    const notes = await db.select().from(NotesTable);
    res.status(200).json({ notes });
  } catch (error) {
    next(new CustomError("Failed to fetch notes", 500));
  }
}

export async function getNote(req: Request, res: Response, next: NextFunction) {
  try {
    const note = await db
      .select()
      .from(NotesTable)
      .where(eq(NotesTable.id, +req.params.id));
    res.status(200).json({ note });
  } catch (error) {
    next(new CustomError("Failed to fetch note", 500));
  }
}

export async function deleteNote(req: Request, res: Response, next: NextFunction) {
  try {
    const note = await db
      .delete(NotesTable)
      .where(eq(NotesTable.id, +req.params.id))
      .returning({
        deletedNoteId: NotesTable.id,
      });
    res.status(200).json({ note });
  } catch (error) {
    next(new CustomError("Failed to delete note", 500));
  }
}

export async function updateNote(req: Request, res: Response, next: NextFunction) {
  try {
    const note = await db
      .update(NotesTable)
      .set(req.body)
      .where(eq(NotesTable.id, +req.params.id))
      .returning();

    res.status(201).json({ note });
  } catch (error) {
    next(new CustomError("Failed to update note", 500));
  }
}

Similar to SQL, Drizzle provides methods like insert, select, update, delete, set, where, and more to interact with the database. The eq function is used to compare two entities. The returning function at the end of the insert, update, and delete functions specifies what Drizzle should return after successful execution. If left empty, it will return all fields. Drizzle offers a wide range of functions to help you achieve your API goals, and they are well-documented in the official documentation.

Validating and Sanitizing Data from Client’s Request

Our app is still missing a crucial component. Consider a scenario where we expect a numerical value in the request body but receive a string instead, or anticipate an email address but receive plain text. Even worse, a malicious actor might attempt to inject code into our database to steal or compromise stored information. We must prevent these scenarios from occurring, and one way to do so is to thoroughly examine client data before it reaches the handler.

We could write custom middlewares to validate and sanitize client data, but a more efficient approach is to utilize the battle-tested express-validator npm package. This package provides a set of middlewares that enable us to inspect client data and ensure it meets our requirements, making our app more secure and robust.

Installing `express-validator`



npm i express-validator

Defining `express-validator` middlewares

Within the src/lib folder, create the validator-functions.ts file and include the following lines of code:

src/lib/validator-functions.ts



import { body, param } from "express-validator";

//Validating and sanitizing title from request body
export function validateNoteTitle() {
  return body("title").notEmpty().isString().trim().escape();
}

//Validating and sanitizing body from request body
export function validateNoteBody() {
  return body("body").notEmpty().isString().trim().escape();
}

//Validating id from route parameter
export function validateIdParam() {
  return param("id").toInt().isInt();
}

To validate individual values from the client request, we utilize method chaining, where the output of the previous method becomes the input for the current method. For the title and body fields, we employ the following methods:

notEmpty(): Validates that the value is not empty
isString(): Validates that the value is a string
trim(): A sanitizer that removes whitespace from both ends of the value, if present
escape(): A sanitizer that replaces special characters, such as < and >, with HTML entities, protecting the server from Cross-Site Scripting (XSS) attacks

For a comprehensive list of validators and sanitizers, along with their uses, refer to the validator.js GitHub repository.

Implementing `express-validator` middleware functions

Now that we have written the validator functions, we can now implement them in our routes. Let’s update our src/routes/notes.ts file:

src/routes/notes.ts



import { Router } from "express";
import { addNote, deleteNote, getAllNotes, getNote, updateNote} from "../handlers/notes.ts";
import { validateIdParam, validateNoteBody, validateNoteTitle} from "../lib/validator-functions.ts";

const notesRouter = Router();

notesRouter.get("/get-note/:id", validateIdParam(), getNote);
notesRouter.get("/get-all-notes", getAllNotes);
notesRouter.post("/add-note", validateNoteBody(), validateNoteTitle(), addNote);
notesRouter.put("/update-note/:id", validateIdParam(), validateNoteBody(), validateNoteTitle(), updateNote);
notesRouter.delete("/delete-note/:id", validateIdParam(), deleteNote);

export default notesRouter;

When an express-validator middleware encounters a validation error, it doesn't terminate the request immediately. Instead, it collects the errors and passes control to the next middleware or handler in the chain. This allows for more flexibility in handling validation errors.

The validationResult() function is a key part of this process. It takes the request object as an argument and returns an object containing the validation errors, if any. By checking the result of validationResult(), we can determine if there were any validation errors and handle them accordingly in the handlers.

Capturing validation errors

Let’s update our src/handlers/notes.ts to account for validation errors:

src/handlers/notes.ts



import { eq } from "drizzle-orm";
import { db } from "../db/db.ts";
import { NotesTable } from "../db/schema.ts";
import { Response, Request, NextFunction } from "express";
import { CustomError } from "../lib/custom-error.ts";
import { validationResult } from "express-validator";

export async function addNote(req: Request, res: Response, next: NextFunction) {
  const result = validationResult(req);
  console.log(result);
  if (!result.isEmpty()) {
    return next(new CustomError(JSON.stringify(result.array()), 400));
  }
  try {
    const note = await db.insert(NotesTable).values(req.body).returning();
    res.status(201).json({ note });
  } catch (error) {
    next(new CustomError("Failed to add note", 500));
  }
}

export async function getAllNotes(req: Request, res: Response, next: NextFunction) {
  try {
    const notes = await db.select().from(NotesTable);
    res.status(200).json({ notes });
  } catch (error) {
    next(new CustomError("Failed to fetch notes", 500));
  }
}

export async function getNote(req: Request, res: Response, next: NextFunction) {
  const result = validationResult(req);
  if (!result.isEmpty()) {
    return next(new CustomError(JSON.stringify(result.array()), 400));
  }
  try {
    const note = await db
      .select()
      .from(NotesTable)
      .where(eq(NotesTable.id, +req.params.id));
    res.status(200).json({ note });
  } catch (error) {
    next(new CustomError("Failed to fetch note", 500));
  }
}

export async function deleteNote(req: Request, res: Response, next: NextFunction) {
  const result = validationResult(req);
  if (!result.isEmpty()) {
    return next(new CustomError(JSON.stringify(result.array()), 400));
  }
  try {
    const note = await db
      .delete(NotesTable)
      .where(eq(NotesTable.id, +req.params.id))
      .returning({
        deletedNoteId: NotesTable.id,
      });
    res.status(200).json({ note });
  } catch (error) {
    next(new CustomError("Failed to delete note", 500));
  }
}

export async function updateNote(req: Request, res: Response,next: NextFunction) {
  const result = validationResult(req);
  if (!result.isEmpty()) {
    return next(new CustomError(JSON.stringify(result.array()), 400));
  }
  try {
    const note = await db
      .update(NotesTable)
      .set(req.body)
      .where(eq(NotesTable.id, +req.params.id))
      .returning();

    res.status(201).json({ note });
  } catch (error) {
    next(new CustomError("Failed to update note", 500));
  }
}

In this updated code, we're using validationResult(req) to check for validation errors. If there are any errors, we're returning a 400 response with the error details. If there are no errors, we can proceed with the logic.

result.array() returns an array of objects, and the CustomError class expects a string message. By using JSON.stringify(), we can convert the error message to a string, which can then be passed to the CustomError class. Remember that we designed our error middleware to accept both JSON and text strings? This is where it comes in handy in this API.

Testing the app

To test the app, insert the following lines of code in the index.ts file:

src/index.ts



import app from "./server.ts";
const port = process.env.PORT || 8000;

app.listen(port, () => {
  console.log(`Server is listening at port ${port}`);
});

Run the app with the following command on the terminal:



npm run dev

I am using Thunder Client VS Code extension (which you can easily install) to test the API endpoints. However, you can any API client of your choice, such as Insomnia and Postman.

Create note with the `/api/add-note` POST endpoint

Great, let's verify that our notes are being stored in the database! Here are the steps to follow:

Open your Turbo dashboard
Click on Databases
Select the database named express-api-project (or the name you chose for your database)
Scroll down and click on the Edit Tables button next to the Generate Token button
In the Tables tab, click on the notes table
You should see a list of notes that you've created using the API

If you see the following screen, that means your server is working correctly and storing data in the database!

Fetching all notes with the /api/get-all-notes GET endpoint

These endpoints worked! You can try the other endpoints yourself.

Conclusion

Great job if you stuck around throughout the guide! You now have a solid foundation on how to build an API using TypeScript, Express, Drizzle, and Turso database. For reference, check out the project's Github Repository. I hope you found this article helpful and enjoyed building this project as much as I did.

A Simple Guide to Setting Up TypeScript with Node.js and Express (2024)

Ibrahim Ayuba — Thu, 16 May 2024 15:03:42 +0000

Typescript is the current industry standard for creating JavaScript applications. It enhances our JavaScript code by adding types, enabling us to build large-scale products that are more maintainable and less error-prone.

In this article, we will discuss how to set up a TypeScript project for an Express app in a few simple steps.

Prerequisites

You should have Node.js installed on your machine.
You should also have a basic knowledge of Node.js and Express.

Create a new folder for your project and initialize a `package.json` file

mkdir typescript-express-server
cd typescript-express-server
npm init -y

The npm init -y prompt creates a new package.json file with the following content:

{
  "name": "article",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  ...
}

Install TypeScript

There are two ways to do this:

Globally

If you install TypeScript globally, you don't have to reinstall it for every project. To install TypeScript globally, run the following command:

npm i -g typescript

Locally

You can also install TypeScript locally for only the current project using the following command:

npm i -D typescript

Install other dependencies

npm i express; npm i -D ts-node @types/express

The -D flag indicates that we're going to need ts-node and @types/express only in development mode. We'll use ts-node to compile and run our TypeScript code.

Generate the ts.config file

If you installed TypeScript globally, generate the tsconfig.json file with the following command:

tsc --init

If you installed it locally, use the following command instead:

npx tsc --init

The ts.config serves as the configuration file for the TypeScript compiler. You can modify this file to customize the compiler settings for your project. It comes with a lot of commented-out options. Comment out and edit the following options:

{
  "compilerOptions": {
    ....

    "module": "NodeNext", 
    "rootDir": "./src",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    ....
  }
}

In the tsconfig.json file above, the settings:

"rootDir": "./src" specifies that the TypeScript compiler will look for source files in the ./src directory.
"outDir": "./dist" specifies that the compiled JavaScript files will be output in the ./dist directory. Later, we'll set up an npm run build command in our package.json that will trigger the compilation process, using these settings to transform our TypeScript code into JavaScript files in the ./dist directory.

File structure

Currently, here's a recommended file structure for your project, omitting the node_modules directory:

├── .env
├── .gitignore
├── package-lock.json
├── package.json
├── src
│  └── index.ts
└── tsconfig.json

Update `package.json` file

{
  "name": "article",
  "version": "1.0.0",
  "main": "dist/index.js",
  "type": "module",
  "scripts": {
    "dev": "node --loader=ts-node/esm --env-file=.env --watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  },
  ...
}

Here's a summary of the changes made in the package.json file:

Main Entry Point: Updated "main": "dist/index.js" to point to the compiled JavaScript file.
Module Type: Changed "type": "module" to enable ES6 imports and exports.
Scripts:
- “dev”: Runs the development server with node and:
  - —-loader=ts-node/esm for compiling and running TypeScript code.
  - --env-file=.env to load environment variables from the .env file.
  - --watch to reload code after every change.
  - src/index.ts as the entry point.
- “build”: Compiles TypeScript code to JavaScript and outputs it to the ./dist folder using tsc (change to npx tsc if you installed TypeScript locally on the current project).
- “start”: Starts the server in production mode.

Create a basic server

In your src/index.ts file, write the following lines of code:

import express, { urlencoded, json } from "express";

const port = process.env.PORT || 8000;
const app = express();

app.use(urlencoded({ extended: true }));
app.use(json());

app.get("/", (req, res) => {
  res.status(200).json({ msg: "Server is up and running" });
});

app.listen(port, () => {
  console.log(`Server is listening at port ${port}`);
});

In your .env file, write the following line:

PORT=3000

Running the program

npm run dev

If everything is working fine you should see Server is listening at port 3000 on your terminal.

Verify your app

Now that your application is running, you can verify that it's working by accessing the URL: http://localhost:3000/.
You can use:

Your web browser to open the URL and see the app in action
Extensions like Thunder Client or Postman to test the API endpoints

Conclusion

This article has guided you through setting up a TypeScript project with Node.js and Express.js, minimizing unnecessary package installations. You've learned to create a efficient development workflow, leveraging TypeScript's benefits while keeping your project lightweight.
I hope you found this tutorial helpful in getting started with TypeScript and Express.js. Happy coding!

Mastering XState Fundamentals: A React-powered Guide

Ibrahim Ayuba — Tue, 16 Apr 2024 13:41:50 +0000

The first article in this series discussed the core differences between the reducer and finite state machine models. In this article, we will dig into the fundamental concepts of XState using the React framework. We'll cover states, events, actions, and guards — providing a solid foundation for building programs with XState.
XState is a robust state management library that leverages the simplicity and power of finite state machines to build efficient, scalable JavaScript or TypeScript applications.
Before we begin, prior knowledge of JavaScript and React is necessary to grasp the content of this article. Familiarity with Redux or React's useReducer() hook would be beneficial but is not mandatory. Lastly, we will be using JavaScript throughout this article.
If you wish to code along, you will need XState and @xstate/react in addition to React.

npm i xstate @xstate/react

Now that we’re on the same page, let us learn about state.

State

Reducer model

When we create apps using the reducer pattern, we need to keep all the data in one spot, called the state. For example, if we're making an API call program, it will include the status, data, and error.

const initialState = {
  status: "idle",
  data: undefined,
  error: undefined,
};

These variables will change throughout the program's lifecycle. When the program is triggered, it transitions from idle to loading. If the API call succeeds, it assigns the returned value to the data property and changes the status from loading to success. Otherwise, it attaches the returned error message to the error property and changes the status from loading to error.

const fsmReducer = (state, action) => {
  switch (state.status) {
    case "idle": {
           //code to move to loading state when triggered.
    }
    case "loading": {
        //move to success if the api call is successful. Otherwise, move to error state.
    },
    case "success" {},
    case "error" {},
     default: {
      return state;
    }
  }
};

In a usual reducer model, we typically switch based on events, not states. However, in the example mentioned, we're switching based on the state, aligning with the principles of finite state machines.
In summary, the reducer model stores all application variables in a central store, while the finite state machine pattern takes a different approach.

Finite State Machines Model

The FSMs pattern distinguishes clearly between the application's status and other data. In the FSMs model, the program's status is referred to as the state, representing the qualitative aspect, while the remaining data represents the quantitative part of the application.

A program can exist in only one state at any given time and has a finite number of possible states. For instance, a light bulb switch can be either in the on or off state.

All other data concerning the application constitutes the quantitative part. For our API call logic, this could be the resolved data from the API call or error message.

Let's redefine the API call program as in the previous example, this time utilizing FSMs with XState.

import { createMachine } from "xstate";

const fetcher = createMachine({
  initial: "idle",
  context: {
    data: undefined,
    error: undefined
  }
  states: {
    idle: {
        //Some code to execute
    },
    loading: {
        //more code
    },
    success: {
        //more code
    },
    error: {
        //more code
    },
  },
});

In XState, states are explicitly defined, and all other data is stored in the context object.

The createMachine() function accepts the application’s logic object as an argument.

You need to specify the initial state of the application, especially if it has multiple states. In this case, its initial state is idle.

Events

Events are occurrences within the system, which can be triggered by a user action, like clicking a button, or by the program itself, such as resolving or rejecting a promise in JavaScript.

Sending Events

When a user interacts with the UI, like clicking a button or typing, we aim to capture these events and respond by executing some code. XState provides a method to capture these UI events and send them to the state machine for proper handling. Additionally, these events can carry additional dynamic information from the UI.

For example, consider a React counter machine. Whenever the user clicks a button, we want to increment the count by a number provided by the UI, 2 in this case.

import { assign, createMachine } from "xstate";
import { useMachine } from "@xstate/react";

const counterMachine = createMachine({
  context: {
    count: 0,
  },
  on: {
    ADD: {
     //code to handle the Add event
    },
  },
});

export default function App() {
  const [snapshot, send] = useMachine(counterMachine);

  return (
    <div>
      <p>count: {snapshot.context.count}</p>
      <button onClick={() => send({ type: "ADD", data: 2 })}>Add two</button>
    </div>
  );
}

XState provides the useMachine() React hook, which returns an array containing the snapshot object and the send function. The snapshot object holds essential details about the state machine, including the context object. Meanwhile, the send function allows us to dispatch events from the UI to the machine for appropriate handling.

Next, we would see how events such as ADD are handled within the machine’s logic.

Handling Events

All state- or program-level events are defined within the on object.

For single-state programs like the counter example, the on object is directly placed on the program logic object.

For multi-state applications like the API-call program, the on object resides within individual states.

It's worth noting that even if an application has multiple states, you can still have an on object with events directly on the program logic object, similar to the counter example. When such top-level events are dispatched to the machine, they take effect regardless of the current state of the application.

const fetcher = createMachine({
  initial: "idle",
  context: {
    data: undefined,
    error: undefined
  },
  states: {
    idle: {
      on: {
        FETCH: {
          target: "loading",
        },
      },
    },
    loading: {
      on: {
        FETCHED: {
          target: "success",
        },
        CANCEL: {
          target: "idle",
        },
      },
    },
    success: {
     on: {
       RELOAD: {
         target: "loading",
       },
     },
    },
  },
});

The idle state allows the FETCH event, while the loading state permits the FETCHED and CANCEL events.

Each of these events is assigned an action object. In this case, the action object contains the target property, specifying the transition or the next state the machine will enter when the event is received.

If the target is not specified, the program will stay in its current state. Apart from transitions, the action object can also include actions, which we'll explore next.

Actions

In addition to transitions, actions are also responses to events. actions can include invoking a function, altering a variable within the context object, or executing asynchronous operations. Next, we’ll learn about each of these common actions in XState.

Changing a Variable

In our counter app example, we utilize the assign action to modify variables within the context object. The syntax is simple and allows us to modify one or multiple variables simultaneously.

const counterMachine = createMachine({
  context: {
    count: 0,
    otherVariable: undefined
  },
  on: {
    ADD: {
      actions: assign({
        count: ({ context, event }) => context.count + event.data,
        otherVariable: ({context, event}) => //new value
      }),
    },
  },
});

Invoking a Function

When an event is dispatched, you might simply want to execute a function, as demonstrated in this case:

const counterMachine = createMachine({
  context: {
    count: 0,
  },
  on: {
    ADD: {
      actions: ({event}) => console.log(event)
    },
  },
});

The above action will merely log the event. Additionally, you can execute multiple actions sequentially by assigning an array of action functions to the actions property.

const counterMachine = createMachine({
  context: {
    count: 0,
  },
  on: {
    ADD: {
      actions: [({event}) => console.log(event),
          assign({
        count: ({event}) => event.data
            })
      ]
    },
  },
});

Performing Asynchronous Operations

XState offers convenient methods to handle asynchronous processes using actors. In this discussion, we'll concentrate on the fromPromise actor, designed for executing promises, including API calls using fetch().

Asynchronous operations via actors have a slight distinction from other actions. While other actions are accessible on the event level within the actions object, actors (employed for asynchronous tasks in XState) are executed via the invoke object, which is only available at the state level.

import { assign, createMachine, fromPromise } from "xstate";
import { useMachine } from "@xstate/react";

const counterMachine = createMachine({
  initial: "idle",
  context: {
    data: undefined,
    error: undefined,
  },
  states: {
    idle: {
      on: {
        LOAD_DATA: {
          target: "loading",
        },
      },
    },
    loading: {
      invoke: {
        src: fromPromise(() =>
          fetch("https://fakestoreapi.com/products/category/jewelery").then(
            (res) => res.json()
          )
        ),
        onDone: {
          target: "success",
          actions: assign({
            data: ({ event }) => event.output,
          }),
        },
        onError: {
          target: "error",
          actions: assign({
            error: ({ event }) => event.error,
          }),
        },
      },
    },
    success: {},
    error: {},
  },
});

export default function App() {
  const [snapshot, send] = useMachine(counterMachine);

  return (
    <div>
      <button onClick={() => send({ type: "LOAD_DATA" })}>Load Data</button>

      {snapshot.value == "loading" && <div>Loading...</div>}

      {snapshot.value == "success" && (
        <ul>
          {snapshot.context.data.map((item) => (
            <li key={item.id}>{item.title}</li>
          ))}
        </ul>
      )}
    </div>
  );
}

When the user clicks on the Load Data button, it triggers the loading state, where the invoke object is executed. We assign the fromPromise() to the src property. The fromPromise() actor requires a callback function that returns a fulfilled or rejected promise. If the promise succeeds, the onDone event is triggered; otherwise, the onError event is called.

Guards

If you need to transition to a particular state or execute certain actions based on the value of a variable within your context object, you can achieve this functionality using guards. Guards are functions that evaluate to either true or false.

Instead of assigning a single action object with transitions and actions, you attach an array of action objects. Each object in this array will include a guard function along with target and actions.

XState executes these objects serially. The first object whose guard evaluates to true will have its target and actions executed.

const counterMachine = createMachine({
  initial: "editing",
  context: {
    todo: "",
  },
  states: {
    editing: {
      on: {
        RECORD_INPUT: {
          actions: assign({
            todo: ({ event }) => event.data,
          }),
        },
        SAVE: [
          {
            guard: ({ context }) => context.todo.length > 0,
            actions: () => console.log("saved"),
          },
          {
            guard: ({ context }) => context.todo.length == 0,
            actions: () => console.log("not saved"),
          },
        ],
      },
    },
  },
});

In this simple todo app, the user is unable to save an empty text or todo.

Conclusion

This article explores the basics of state machines using XState. It covers the fundamentals of states, events, actions, and guards. Each of these concepts has more depth to explore, including parallel states, entry and exit actions, and input and output, all of which you learn more about in the documentation.

XState is a powerful library with comprehensive documentation. Keeping the documentation handy while building your next app with XState will be invaluable.

Reducer vs. Finite State Machines: Understanding the Paradigm Shift

Ibrahim Ayuba — Mon, 25 Mar 2024 11:47:25 +0000

Alex boarded the bus with two of his kids. The kids were disturbing everyone around, but Alex remained silent. At this point, everyone grew angry with Alex, assuming he wouldn't discipline his kids, thus deeming him unreasonable.

Then, a fellow passenger shouted at Alex about the whole situation. Absent-minded, Alex realized what was happening and apologized to everyone. He added that his wife, the mother of the kids, had just passed away, and he was deeply troubled, oblivious to his surroundings as a result.

At this point, everyone around understood the situation and felt remorseful for hastily judging Alex's character without understanding his circumstances. If they had known about Alex's state, they would likely have behaved differently. Instead, they focused on the event—the playing children—and reacted, something most of them later regretted.

This phenomenon, from the field of Social Psychology, is called the Fundamental Attribution Error (FAE). It involves judging a person's behavior solely based on their disposition, such as temperament and personality traits, while completely ignoring their situation:

In social psychology, fundamental attribution error, also known as correspondence bias or attribution effect, is a cognitive attribution bias where observers underemphasize situational and environmental factors for the behavior of an actor while overemphasizing dispositional or personality factors.
Source: Fundamental attribution error (Wikipedia)

In this article, we'll delve into the paradigm shift between the reducer and finite state machines models and explore how the FAE can help us make more sense of these patterns.

The Reducer Paradigm

In our earlier story, the fellow passengers didn't take into account Alex's state before reacting to the children's disturbance. Their response was solely based on the event.

Similarly, the reducer model operates on an event-first approach, focusing solely on the episode and responding accordingly. React's useReducer() hook and state management libraries like Redux rely on this paradigm.

When developing a straightforward application like a counter, the reducer pattern poses no challenges. You can easily employ React's useReducer() hook and design logic for actions such as ADD_COUNT, REDUCE_COUNT, and RESET without needing to consider additional states—life is good.

However, what about more complex applications, such as an API-call logic that can exist in multiple states? The reducer logic for such an app might resemble the following:

const reducerFetcher = (state, action) => {
  switch (action.type) {
    case "LOAD_DATA": {
        return { ...state, status: "loading" }
    }
    case "LOADED": {
        return { ...state, status: "success" }
    }
    case "CANCEL": {
        return { ...state, status: "idle" };
    }
    case "RELOAD": {
        return { ...state, status: "loading" };
    }
    case "ERROR": {
        return {...state, status: "error" }
    }
    default: {
      return state;
    }
  }
};

By simply examining this logic, you might notice some issues. For instance, if the LOAD_DATA event fires while the app is already in a loading state, the application would initiate the loading process anew. This indicates that the reducer is open to processing any event at all times, which is not efficient. We need to take into account not only the event but also the current state to ensure more effective handling.

The Finite State Machine Paradigm

Back to our story. If the passengers had been aware of or inquired about Alex’s mood, they would have known how to react more appropriately. This could have spared them the burden of anger and frustration, as well as the embarrassing moment when they learned about the man’s situation.

The finite state machines pattern circumvents the Fundamental Attribution Error by prioritizing a state-first approach. This model evaluates the current state before determining how to respond to an event.

Every application you've ever built operates within a finite number of states, whether you've consciously acknowledged it or not. Take, for example, an audio player. At any given time, it can only be in one of several states: idle, loading, playing, or paused.

Each state permits a subset of all possible events within the application. Events can also trigger a change in state, known as a transition. In addition to transitions, events can prompt actions such as invoking a function, generating another event, or executing asynchronous operations.

Now, let's reimplement the same API-call logic we previously discussed using the useReducer() hook, but this time adhering to the principles of finite state machines. There are two ways to accomplish this:

The Implicit Way

const reducerFetcher = (state, action) => {
  switch (action.type) {
    case "FETCH": {
      if (state.status === "idle") {
        return { ...state, status: "loading" };
      }
      return state;
    }
    case "FETCHED": {
      if (state.status === "loading") {
        return { ...state, status: "success" };
      }
      return state;
    }
    case "CANCEL": {
      if (state.status === "loading") {
        return { ...state, status: "idle" };
      }
      return state;
    }
    case "RELOAD": {
      if (state.status === "success" || state.status === "error") {
        return { ...state, status: "loading" };
      }
      return state;
    }
    case "ERROR": {
      if(state.status === "loading"){
        return {...state, status: "error" }
      }
    }
    default: {
      return state;
    }
  }
};

Indeed, while we continue to evaluate events, we now prioritize checking the state before reacting to them, ensuring that certain events are restricted to specific states, which aligns with our objective.

However, the logic becomes convoluted, making it challenging to discern the current mode of our application and the events associated with individual states. Moreover, as the application scales, the potential for nested if/else statements increases, making it difficult to manage and prone to errors.

The Explicit Way (Better Approach)

const initialState = {
  status: "idle",
  data: undefined,
  error: undefined,
};

const fsmReducer = (state, action) => {
  switch (state.status) {
    case "idle": {
      if (action.type === "FETCH") {
        return { ...state, status: "loading" };
      }
      return state;
    }
    case "loading": {
      if (action.type === "FETCHED") {
        return { ...state, status: "success" };
      }
      if (action.type === "CANCEL") {
        return { ...state, status: "idle" };
      }
      if (action.type === "ERROR") {
        return { ...state, status: "error" };
      }
      return state;
    }
    case "success": {
      if (action.type === "RELOAD") {
        return { ...state, status: "loading" };
      }
      return state;
    }
    case "error": {
      if (action.type === "RELOAD") {
        return { ...state, status: "loading" };
      }
      return state;
    }
  }
};

Instead of switching based on the event, we're now switching based on the state. This approach allows us to reason with our logic more easily because the states and their associated allowed events are clearly defined.

However, upon closer inspection, we're still applying the reducer pattern, but this time only locally within individual states.

Embracing the well-established finite state machine paradigm can significantly alleviate the pains of development:

The traditional techniques (such as the event-action paradigm) neglect the context and result in code riddled with a disproportionate number of convoluted conditional logic (in C/C++, coded as deeply nested if-else or switch-case statements). If you could eliminate even a fraction of these conditional branches, the code would be much easier to understand, test, and maintain, and the sheer number of convoluted execution paths through the code would drop radically, perhaps by orders of magnitude.
Source: Who Moved My State?

Conclusion

Finite state machines offer a robust solution for managing complex behaviors in event-driven applications. While the reducer pattern provides a solid foundation, FSMs elevate this concept by promoting a structured state-first approach, thereby minimizing the requirement for convoluted logic.

This post marks the first installment of a four-part series, encompassing everything you need to begin constructing frontend applications using the robust principles of finite state machines. We've established the groundwork for comprehending FSMs in this article and will delve deeper in the next. Subsequent articles will concentrate on leveraging XState, a finite state machines library for JavaScript runtimes, for developing frontend applications.

If you found this article informative and are intrigued by the FSMs pattern in JavaScript, keep an eye out for the upcoming articles in this series. Stay tuned for more insights and practical applications!

Unleashing the Power of Actors in Frontend Application Development

Ibrahim Ayuba — Fri, 22 Mar 2024 09:45:47 +0000

In backend development, threads have traditionally been used to achieve concurrency, which aims to maximize computing power. However, issues arise from the way threads communicate via shared mutable state or memory. Problems like race conditions, memory visibility, and deadlock occur when synchronizing this shared state. Addressing these problems adds complexity and makes development challenging.

On the other hand, actors eschew shared memory entirely. Each actor in the system possesses mutable state but refrains from sharing it with other actors:

Actor programming retains mutable state but avoid sharing it.
Source: Seven Concurrency Models in Seven Weeks

Also, actors run concurrently with each other and communicate via messaging.

This innovative model is employed by languages, including Elixir to achieve fault tolerance and resilience in software.

In this article, we will explore how to harness the actor paradigm in frontend development to construct robust, scalable, and maintainable software.

Why Actors in the Frontend?

State management can be challenging, particularly in frontend applications. When developing a non-trivial application using React, the typical approach involves employing a state management library like Redux, Alt, or similar tools. These tools advocate for a "single source of truth," where all application state resides in a single object accessible to all components. This simplifies tasks such as hydration and debugging:

[...] This makes it easy to create universal apps, as the state from your server can be serialized and hydrated into the client with no extra coding effort. A single state tree also makes it easier to debug or inspect an application.
Source: Redux Style Guide

However, this approach often leads to unnecessary re-renders. Whenever the state changes, all components reliant on data from the central state re-render, resulting in performance issues. To mitigate this, techniques like memoization, caching, and selectors are commonly employed. While effective, these solutions introduce additional complexity to the codebase.

Actors offer an alternative by avoiding the concept of a "single source of truth." Instead, each actor maintains its own private local state:

An actor is an independent virtual processor with its own local (and private) state.
Source: The Pragmatic Programmer

This characteristic of the actor model can be leveraged in frontend applications.

Before delving into the implementation of actors in the frontend, let's explore the three fundamental characteristics of actors.

Send

In the actor model, communication between actors occurs through the exchange of messages. These messages are immutable and are sent asynchronously in a fire-and-forget manner. Additionally, actors handle messages they receive one at a time.

In essence, the actor model operates entirely through messaging:

[…] the most important aspect of actors is that you build applications by sending and receiving messages.
Source: Akka in Action

Create

Actors have the ability to create or spawn additional actors, thus establishing a system. This system resembles a tree structure, allowing any actor, irrespective of its location, to communicate with all other actors within the system.

Designing the Next Behavior

When an actor receives a message, it may change its behavior, which will be used for the next message it receives. For instance, imagine an actor that fetches data from an external API. It can exist in idle, loading, success, or error states.

So, if the actor is in the idle state and receives a message to load data, it will change its state to loading. When the next message arrives, the current state will be loading. Essentially, that's how actors change their behavior or state.

Finite state machines are useful for modeling actor behaviors.

Implementing Actors in Frontend Applications

XState is an excellent library that simplifies the utilization of actors in JavaScript applications. While this article focuses on using React, these principles apply equally well to other frameworks. In fact, they can be implemented anywhere JavaScript is executed.

Creating Actors

For actors to communicate with each other, they need to be part of the same system. The most effective approach is to establish one parent actor, which serves as the root actor. From this root actor, we can create a hierarchy of actors that can exchange messages with one another.

In this example, we'll utilize React's context API. However, there’s another way, which is highlighted in this article on the Stately blog.

const rootMachine = createMachine({
  entry: [
    spawnChild(cartActor, { systemId: "cart" }),
    spawnChild(favoritesActor, { systemId: "favorites" }),
  ],
});

export const rootContext = createActorContext(rootMachine);

const RootContext = ({ children }) => {
  return <rootContext.Provider>{children}</rootContext.Provider>;
};

export default RootContext;

The createActorContext(rootMachine) function creates an actor, specifically the root actor, and makes it accessible throughout our application via React Context. More information about this function can be found in the XState docs.

The spawnChild() function is employed to create child actors. It requires the logic of our actor as the first argument and an object with a systemId as the second argument.

Afterward, we can use the assigned systemId, represented as a string, to send messages to the actor or to access its internal state from a component using useSelector() or from another actor using getSnapshot().

Actor Communication

As mentioned earlier, actors can exchange messages with other actors. In XState, this process is straightforward. To maintain consistency, every component containing logic should be linked to an actor. Moreover, components should exclusively communicate with their associated actors.

Using the actorRef, we can dispatch messages to the actor either from within our component or from another actor.

Suppose we aim to add a product to our cart whenever the addToCart button is clicked. This operation involves four steps:

First Step

When the user clicks on the button, we capture the click event and send a message to the btnActor using btnActorRef.send():

const AddToCartBtn = ({ product: { btnActorRef, ...product } }) => {

  const addToCart = (e) => {
    e.preventDefault();
    btnActorRef.send({ type: "ADD_PRODUCT_TO_CART", product });
  };
  return (
    <button
      className="btn bg-[#EF6024] border-[#EF6024] hover:scale-105 hover:bg-[#EF6024] hover:border-[#EF6024] w-full text-white"
      onClick={addToCart}
    >
      Add To Cart
    </button>
  );
};

Second Step

The btnActor would receive the message, possibly execute some actions, and subsequently send another message to the cartActor using the sendTo() function.

The first argument the sendTo() receives is the actorRef, which we can obtain using system.get() along with the systemId we previously assigned. In this case, it would be cart:

import { createMachine sendTo, assign } from "xstate";

export const addToCartBtnActor = createMachine({
      on: {
        ADD_PRODUCT_COUNT: {
          target: "active",
          actions: sendTo(
        ({ system }) => system.get("cart"),
            ({ event }) => ({ type: "ADD_TO_CART", product: 
            event.product })),
        },
    }
});

Third Step

The cartActor receives the message and updates its internal cart store accordingly, either by adding the product or by updating its count if the product already exists:

import { createMachine, assign } from "xstate";

export const cartActor = createMachine({
  context: {
    cart: [],
        cartCount: 0,
  },
  on: {
    ADD_TO_CART: {
      actions: [assign({
      cart: ({ context, event }) => {
        const isInCart = context.cart.find(
          (product) => product.id === event.product.id
        );
        if (isInCart) {
          return context.cart.map((product) => {
            if (product.id === isInCart.id)
              return { ...product, count: product.count + 1 };
            return product;
          });
        }
        return context.cart.concat({ ...event.product, count: 1});
      },
    }),
  assign({
     cartCount: ({ context }) => context.cart.map((item) => item.count).reduce((acc, cv) => acc + cv, 0),
    })],
 },
});

Fourth Step

Finally, the cartActor updates its state accordingly, which will reflect in the cart component:

import { useSelector } from "@xstate/react";
import { rootContext } from "../../RootContext";
import { HiShoppingCart } from "react-icons/hi2";

const Cart = () => {
  const machineRef = rootContext.useActorRef().system.get("cart");
  const { cartCount } = useSelector(machineRef, (state) => state.context);
  return (
    <div className="indicator grid grid-cols-2">
      <span className="indicator-item badge badge-secondary bg-red-400">
        {cartCount}
      </span>
      <HiShoppingCart className="text-2xl" />
    </div>
  );
};

Designing the Next Behavior

Whenever an actor receives a message, it can decide to change its state and perform certain side effects or actions accordingly:

When an event instance is dispatched, the state machine responds by performing actions, such as changing a variable, performing I/O, invoking a function, generating another event instance, or changing to another state. Source: A crash course in UML state machines

For instance, when the user clicks on the like button of a product, the actor representing the favorites component might toggle the product's like state. If the product was initially liked, it would be unliked, and vice versa. Below is the logic for the favorites component actor:

import { createMachine } from "xstate";
const favoritesActor = createMachine({
  id: 'favorites',
  initial: 'unliked',
  states: {
    liked: {
      on: {
        TOGGLE: 'unliked'
      }
    },
    unliked: {
      on: {
        TOGGLE: 'liked'
      }
    }
  }
});

This machine has two states, liked and unliked, and transitions between them occur when the TOGGLE event is triggered.

Conclusion

The actor paradigm presents a promising approach to developing robust and scalable frontend applications. By steering clear of a global shared state and promoting independent communication through messaging, actors can alleviate the challenges linked with state management. As the industry persists in adopting new paradigms, the actor model retains its value as a potent tool for attaining high-performance and dependable frontend solutions.

DEV Community: Ibrahim Ayuba

Building a Scalable REST API with TypeScript, Express, Drizzle ORM, and Turso Database: A Step-by-Step Guide

Why Learn Express?

What the Guide Covers

Prerequisites

Setting Up A TypeScript Project with Express

1. Generating and configuring package.json file

2. Installing starter dependencies

3. Generating and configuring tsconfig.json

Recommended starter file structure for the project

Express Middleware

Without middleware

With middleware

How to define an express middleware

How to use an express middleware

Error middleware

Setting up the Error Middleware

Setting up not-found middleware

Setting up server.ts file

Setting up the Turso Database and Drizzle ORM

How to set up a Turso database

Installing necessary packages for our database

Create the Drizzle configuration file

Connect Turso database with Drizzle

Create Notes Schema and Migrations

Creating the notes schema

Generating migrations

Apply migrations

Creating Notes Router in a Modular Way

Express Router function explained

Creating the notesRouter object

Creating the Notes Handlers

Validating and Sanitizing Data from Client’s Request

Installing express-validator

Defining express-validator middlewares

Implementing express-validator middleware functions

Capturing validation errors

Testing the app

Create note with the /api/add-note POST endpoint

Fetching all notes with the /api/get-all-notes GET endpoint

Conclusion

A Simple Guide to Setting Up TypeScript with Node.js and Express (2024)

Prerequisites

Create a new folder for your project and initialize a package.json file

Install TypeScript

Globally

Locally

Install other dependencies

Generate the ts.config file

File structure

Update package.json file

Create a basic server

Running the program

Verify your app

Conclusion

Mastering XState Fundamentals: A React-powered Guide

State

Reducer model

Finite State Machines Model

Events

Sending Events

Handling Events

Actions

Changing a Variable

Invoking a Function

Performing Asynchronous Operations

Guards

Conclusion

Reducer vs. Finite State Machines: Understanding the Paradigm Shift

The Reducer Paradigm

The Finite State Machine Paradigm

The Implicit Way

The Explicit Way (Better Approach)

Conclusion

Unleashing the Power of Actors in Frontend Application Development

Why Actors in the Frontend?

Send

Create

Designing the Next Behavior

Implementing Actors in Frontend Applications

1. Generating and configuring `package.json` file

3. Generating and configuring `tsconfig.json`

Setting up `server.ts` file

Creating the `notesRouter` object

Installing `express-validator`

Defining `express-validator` middlewares

Implementing `express-validator` middleware functions

Create note with the `/api/add-note` POST endpoint

Create a new folder for your project and initialize a `package.json` file

Update `package.json` file