DEV Community: Nicholas Tsang

Handling custom error responses from ExpressoTS with TanStack Query, and NextJS

Nicholas Tsang — Thu, 05 Sep 2024 18:38:46 +0000

Table of contents:

Introduction
Back End
DeckView Page Part 1
DeckView Page Part 2
DeckView Page Part 3
Conclusion

Introduction

Building robust web applications often means handling errors in ways that keep users informed without breaking their experience. In this blog, I'll walk you through how I’ve integrated custom error handling in CookieDeck using ExpressoTS, TanStack Query (formerly known as React Query), and Next.js. In this example, we will look at how I leverage custom error responses from ExpressoTS and TanStack Query to load a page based on what type of response I get.

Back End

Let's start by looking at the business logic in the back end:

// \src\deck\update\incrementview\deck-update-incrementview.usecase.ts
import { provide } from "inversify-binding-decorators";
import { DeckRepository } from "../../deck.repository";
import { AppError, Report, StatusCode } from "@expressots/core";
import {
  IDeckUpdateIncrementviewRequestDto,
  IDeckUpdateIncrementviewResponseDto,
} from "./deck-update-incrementview.dto";
import { DeckEntity } from "../../deck.entity";
import { ISimpleDeckFindResponseDto } from "../../find/deck-find.dto";

@provide(DeckUpdateIncrementviewUsecase)
export class DeckUpdateIncrementviewUsecase {
  constructor(private deckRepository: DeckRepository, private report: Report) {}
  public async execute(
    payload: IDeckUpdateIncrementviewRequestDto,
    userId: string
  ): Promise<IDeckUpdateIncrementviewResponseDto | AppError> {
    const doesDeckExist: ISimpleDeckFindResponseDto | null =
      await this.deckRepository.simpleFindById(payload.id);
    if (!doesDeckExist) {
      throw this.report.error(
        `Deck ${payload.id} not found`,
        StatusCode.NotFound,
        `DeckUpdateIncrementviewUsecase`
      );
    }
    if (
      doesDeckExist.creator_id !== userId &&
      doesDeckExist.visibility.toLowerCase() === "private"
    ) {
      throw this.report.error(
        `User is not authorized to access deck ${payload.id}`,
        StatusCode.BadRequest,
        `DeckUpdateIncrementviewUsecase`
      );
    }

    const res: DeckEntity | null = await this.deckRepository.incrementDeckView(
      payload.id
    );
    if (!res) {
      throw this.report.error(
        "Deck views failed to increment",
        StatusCode.BadRequest,
        `DeckUpdateIncrementviewUsecase`
      );
    }
    return {
      id: res.id,
      message: "Deck updated successfully.",
    };
  }
}

The code can be split into two parts. In the first part, the code checks if a deck with the id defined in payload.id exists. If it doesn't exist, throw an error stating it does not exist. If it does exist, if the user id from the request is not equal to the deck's creator id and the deck's visibility is set to "private", the code throws an unauthorized user error. Otherwise, proceed to the second part, where the code calls the "incrementDeckView" function to increment the deck's view count by +1. If the response is falsy, throw an error. Otherwise, return a success response to the client.

You may have noticed the code imports "Report". This is ExpressoTS' standardized error reporting class to ensure formatting consistency in error messages that are returned to clients. In order to use it, it must be passed into the constructor of the usecase.

The error responses and logs generated from the aforementioned usecase are as follows.

{
    "statusCode": 400,
    "error": "User is not authorized to access deck 69e2badc-a350-4107-88ef-4979716ce2ec"
}

{
    "statusCode": 404,
    "error": "Deck 69e2badc-a350-4107-88ef-4979716ce2ed not found"
}

[ExpressoTS] 2024-09-05 11:25:50 a.m. [PID:5812] ERROR [DeckUpdateIncrementviewUsecase] Deck 69e2badc-a350-4107-88ef-4979716ce2ed not found
[ExpressoTS] 2024-09-05 11:25:56 a.m. [PID:5812] ERROR [DeckUpdateIncrementviewUsecase] User is not authorized to access deck 69e2badc-a350-4107-88ef-4979716ce2ec

ExpressoTS has a middleware function called "ValidateDTO" for checking and validating the request from the client. This is what the generated error response looks like when validation fails:

{
    "errorCode": 400,
    "errorMessage": "Bad Request",
    "DTO": [
        {
            "property": "id",
            "messages": [
                "id must be a UUID"
            ]
        }
    ]
}

Now that I've covered the back end, let's see the front end code for incrementing deck views. Here is the deck viewing page in its entirety:

// app\(primary)\deck\[id]\page.tsx
"use client";
import { useState } from "react";
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
import { DeckFindResponseDataDTO } from "@/services/deck/find/findDeckDTO";
import DeckInfo from "@/components/deckpage/DeckInfo";
import CardSearch from "@/components/deckpage/CardSearch";
import DeckSlotDisplay from "@/components/deckpage/DeckSlotDisplay";
import { DeckslotFindResponseDTO } from "@/services/deckslot/find/deckslot-find.dto";
import { FindDeck } from "@/services/deck/find/findDeck";
import { DeckSlotFindByDeckId } from "@/services/deckslot/find/bydeckId/deckslot-find-bydeckid";
import { Switch } from "@/components/ui/switch";
import { Label } from "@/components/ui/label";
import DeckPageFooter from "@/components/deckpage/DeckPageFooter";
import { DeckPageDropDownMenu } from "@/components/deckpage/DeckPageDropDownMenu";
import { IncrementDeckView } from "@/services/deck/update/incrementview/incrementDeckView";
import { createClient } from "@/utils/supabase/client";

export default function DeckView({ params }: { params: { id: string } }) {
  const supabase = createClient();
  const [viewMode, setViewMode] = useState<"en" | "kr">("en");
  const queryClient = useQueryClient();

  const { data: userData, isLoading: isUserAuthenticated } = useQuery({
    queryKey: ["getUser"],
    queryFn: async () => {
      const {
        data: { user },
      } = await supabase.auth.getUser();
      return user;
    },
    retry: false, // No retries for PATCH request
    refetchOnWindowFocus: false, // Avoid refetch on window focus
  });

  const {
    data: patchResponse,
    isLoading: isPatchLoading,
    error: incrementViewError,
  } = useQuery({
    queryKey: ["patchDeck", params.id],
    queryFn: () => IncrementDeckView({ id: params.id }),
    retry: false, // No retries for PATCH request
    refetchOnWindowFocus: false, // Avoid refetch on window focus
  });

  const { data: displayDeck, isLoading: isDeckLoading } =
    useQuery<DeckFindResponseDataDTO>({
      queryKey: ["deck", params.id],
      queryFn: () => FindDeck(params.id),
      retry: false,
      refetchOnWindowFocus: false, // Avoid refetch on window focus
      enabled: !!patchResponse, // Only run if PATCH request is successful
    });

  const { data: deckSlots, isLoading: isDeckSlotsLoading } = useQuery<
    DeckslotFindResponseDTO[]
  >({
    queryKey: ["deckSlots", params.id],
    queryFn: async () => {
      const response = await DeckSlotFindByDeckId(params.id);
      return response.deckslots || [];
    },
    retry: false,
    refetchOnWindowFocus: false, // Avoid refetch on window focus
    enabled: !!patchResponse, // Only run if PATCH request is successful
  });

  const updateDeckMutation = useMutation({
    mutationFn: FindDeck,
    onSuccess: (data) => {
      queryClient.setQueryData(["deck", params.id], data);
    },
  });

  const updateDeckSlotsMutation = useMutation({
    mutationFn: DeckSlotFindByDeckId,
    onSuccess: (data) => {
      queryClient.setQueryData(["deckSlots", params.id], data.deckslots || []);
    },
  });

  const toggleViewMode = () => {
    setViewMode((prev) => (prev === "en" ? "kr" : "en"));
  };

  if (
    isPatchLoading ||
    isDeckLoading ||
    isDeckSlotsLoading ||
    isUserAuthenticated
  ) {
    return (
      <div className="flex w-full flex-1 flex-col items-center gap-20">
        <div className="w-full">
          <div className="py-6 text-center font-bold">Loading deck...</div>
        </div>
      </div>
    );
  }

  if (incrementViewError) {
    return (
      <div className="flex w-full flex-1 flex-col items-center gap-20">
        <div className="w-full">
          <div className="py-6 text-center font-bold">
            {incrementViewError.message}
          </div>
        </div>
      </div>
    );
  }

  const isOwner: boolean | null | undefined =
    userData && userData.id === displayDeck?.creator_id;

  return (
    <div className="flex min-h-screen flex-col">
      <div className="flex-grow pb-32">
        <DeckInfo
          displayDeck={displayDeck}
          deckslots={deckSlots || []}
          onUpdate={() => updateDeckMutation.mutate(params.id)}
          isOwner={isOwner}
          viewMode={viewMode}
          setViewMode={setViewMode}
        />
        <div className="my-4 flex items-center justify-center space-x-2">
          {isOwner && <DeckPageDropDownMenu deckId={params.id} />}
          <Switch id="view-mode" onCheckedChange={toggleViewMode} />
          <Label htmlFor="view-mode">{viewMode === "en" ? "EN" : "KR"}</Label>
          {isOwner && <CardSearch deckId={params.id} viewMode={viewMode} />}
        </div>
        <DeckSlotDisplay
          deckslots={deckSlots || []}
          onUpdate={() => [
            updateDeckSlotsMutation.mutate(params.id),
            updateDeckMutation.mutate(params.id),
          ]}
          viewMode={viewMode}
          setViewMode={setViewMode}
          isOwner={isOwner}
        />
        <DeckPageFooter deckslots={deckSlots || []} />
      </div>
    </div>
  );
}

DeckView Page Part 1

It's a lot to take in, so I'll be splitting the Page into three parts and explaining them separately. For the first (and largest) part, I want to cover the actual view increment code.

export default function DeckView({ params }: { params: { id: string } }) {
  const supabase = createClient();
  const [viewMode, setViewMode] = useState<"en" | "kr">("en");
  const queryClient = useQueryClient();

  const { data: userData, isLoading: isUserAuthenticated } = useQuery({
    queryKey: ["getUser"],
    queryFn: async () => {
      const {
        data: { user },
      } = await supabase.auth.getUser();
      return user;
    },
    retry: false, // No retries for PATCH request
    refetchOnWindowFocus: false, // Avoid refetch on window focus
  });

  const {
    data: patchResponse,
    isLoading: isPatchLoading,
    error: incrementViewError,
  } = useQuery({
    queryKey: ["patchDeck", params.id],
    queryFn: () => IncrementDeckView({ id: params.id }),
    retry: false, // No retries for PATCH request
    refetchOnWindowFocus: false, // Avoid refetch on window focus
  });
}

This page takes in a string called "id" as a parameter. I'm using "useState" to keep track of what the displayed language is. Since this page is a client component, we can use TanStack Query's "useQuery" hook to fetch both the user data and increment the view count of the deck by 1. Before I cover the rest of the page, I want to jump in to the code for IncrementDeckView, as that is the main focus of this blog:

// services\deck\update\incrementview\incrementDeckView.ts
"use server";
import { MakeApiRequest } from "@/services/baseApiRequest";
import {
  DeckUpdateIncrementviewRequestDTO,
  DeckUpdateIncrementviewResponseDataDTO,
  DeckUpdateIncrementviewResponseDTO,
} from "./deck-update-incrementview.dto";
import {
  DeckUpdateIncrementviewRequestSchema,
  DeckUpdateIncrementviewResponseSchema,
} from "./deck-update-incrementview.schema";
import { ENV } from "@/env";

//can use this as an example for error handling
export async function IncrementDeckView(
  deckUpdateIncrementviewRequestData: DeckUpdateIncrementviewRequestDTO
): Promise<DeckUpdateIncrementviewResponseDataDTO> {
  try {
    const deckUpdateIncrementviewUrl =
      ENV.BACKEND_URL + "/deck/update/incrementview";
    const deckUpdateIncrementviewResponse: DeckUpdateIncrementviewResponseDTO =
      await MakeApiRequest({
        url: deckUpdateIncrementviewUrl,
        method: "PATCH",
        requestSchema: DeckUpdateIncrementviewRequestSchema,
        responseSchema: DeckUpdateIncrementviewResponseSchema,
        data: deckUpdateIncrementviewRequestData,
      });
    return deckUpdateIncrementviewResponse.data as DeckUpdateIncrementviewResponseDataDTO;
  } catch (error) {
    console.log("Error incrementing deck view:");
    throw error;
  }
}

I'm defining DTOs (Data Transfer Objects) for request validation before sending it to the back end. In a nutshell, the "MakeApiRequest" function takes in the url to the back end as a string, a method, a request schema, a response schema, and the request data as arguments. It performs schema validation of the input data, sends a request to the back end upon successful validation, validates the response data, and returns it if the response validation is successful.

Here is the code for the request and response schemas. I'm using zod to do this on the front end:

// services\deck\update\incrementview\deck-update-incrementview.schema.ts
import { z } from "zod";

export const DeckUpdateIncrementviewRequestSchema = z.object({
  id: z.string().uuid({
    message: "id must be a valid UUID.",
  }),
});

export const DeckUpdateIncrementviewResponseDataSchema = z.object({
  id: z.string().uuid({
    message: "id must be a valid UUID.",
  }),
  message: z.string().optional(),
});

export const DeckUpdateIncrementviewResponseSchema = z.object({
  statusCode: z
    .number({
      required_error: "statusCode is required",
    })
    .min(100)
    .max(599),
  data: DeckUpdateIncrementviewResponseDataSchema,
});

The request schema checks if the input id is a UUID. The data from a successful ExpressoTS response contains a statusCode and data property. In this case, the data will contain an id (which must be a UUID) and an optional message (as a string).

In a separate file, I've converted the schemas into a type to reduce the total number of times I need to type
"z.infer".

// services\deck\update\incrementview\deck-update-incrementview.dto.ts
import { z } from "zod";
import {
  DeckUpdateIncrementviewRequestSchema,
  DeckUpdateIncrementviewResponseSchema,
  DeckUpdateIncrementviewResponseDataSchema,
} from "./deck-update-incrementview.schema";

type DeckUpdateIncrementviewRequestDTO = z.infer<
  typeof DeckUpdateIncrementviewRequestSchema
>;
type DeckUpdateIncrementviewResponseDTO = z.infer<
  typeof DeckUpdateIncrementviewResponseSchema
>;
type DeckUpdateIncrementviewResponseDataDTO = z.infer<
  typeof DeckUpdateIncrementviewResponseDataSchema
>;

export type {
  DeckUpdateIncrementviewRequestDTO,
  DeckUpdateIncrementviewResponseDTO,
  DeckUpdateIncrementviewResponseDataDTO,
};

Let's now cover the "MakeApiRequest" function in more detail:

// services\baseApiRequest.ts
import { z, ZodError } from "zod";
import axios, { AxiosError, Method } from "axios";
import { createClient } from "@/utils/supabase/server";
import { ErrorResponseSchema } from "@/utils/error.schema";
import { ResponseError } from "@/utils/responseError";

async function MakeApiRequest<
  TRequest extends z.ZodType,
  TResponse extends z.ZodType
>({
  url,
  method,
  requestSchema,
  responseSchema,
  data,
}: {
  url: string;
  method: Method;
  requestSchema: TRequest;
  responseSchema: TResponse;
  data: z.infer<TRequest>;
}): Promise<z.infer<TResponse>> {
  const supabase = createClient();
  const {
    data: { session },
  } = await supabase.auth.getSession();

  // Trim whitespace from all string data
  const trimmedData = Object.fromEntries(
    Object.entries(data).map(([key, value]) => [
      key,
      typeof value === "string" ? value.trim() : value,
    ])
  );
  const validData = requestSchema.parse(trimmedData);

  let apiResponse: z.infer<TResponse> = {
    statusCode: 500,
    data: {
      error: "Default error",
    },
  } as z.infer<TResponse>;

  try {
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
    };

    if (session) {
      headers["Authorization"] = `Bearer ${session.access_token}`;
    }

    const config = {
      method,
      url,
      headers,
      ...(method === "GET" ? { params: validData } : { data: validData }),
    };
    const res = await axios(config);
    if (res.data) {
      apiResponse = responseSchema.parse({
        statusCode: res.status,
        data: res.data,
      });
    }
  } catch (error) {
    if (axios.isAxiosError(error)) {
      const { response } = error as AxiosError;
      const errorParse = ErrorResponseSchema.safeParse({
        statusCode: response?.status || 500,
        data: response?.data || { error: error },
      });
      if (errorParse.success) {
        throw new ResponseError({
          name: "RESPONSE_ERROR",
          message:
            errorParse.data.data.error ||
            errorParse.data.data.errorMessage ||
            error.message,
          cause: error,
        });
      }
      throw error as AxiosError;
    }
    if (error instanceof ZodError) {
      throw error as ZodError;
    }
    throw error as Error;
  }
  return apiResponse;
}

export { MakeApiRequest };

Before entering the try/catch block, the code gets the current user session data with "supabase.auth.getSession()". Then, for each property of the input data that is a string, the code trims all leading and ending whitespace before validating it with the zod schemas defined in the previous code snippet. Finally, a default response is defined. Within the try block, the code attempts to extract the the access token from the user session and use it as the "Authorization" request header. The code then defines an Axios configuration, in which the validated input is added to the request params for "GET" requests. For every other type of request, the inputs are added to the request data. The request is then sent to the back end with the previously defined configuration and the response data is parsed with the previously defined zod response schema. In the catch block, the code checks for different types of errors and throws them. If it is an Axios Error, the code attempts to parse the error with a predefined schema, which I will show below:

// utils\error.schema.ts
import { z } from "zod";
export const ErrorResponseDataSchema = z.object({
  message: z.string().optional(),
  error: z.string().optional(),
  //DTO validation failure from the backend
  errorCode: z.number().min(100).max(599).optional(),
  errorMessage: z.string().optional(),
  DTO: z
    .array(
      z.object({
        property: z.string(),
        messages: z.array(z.string()),
      })
    )
    .optional(),
});

export const ErrorResponseSchema = z.object({
  statusCode: z.number().min(100).max(599),
  data: ErrorResponseDataSchema,
});

export type ErrorResponseDataDTO = z.infer<typeof ErrorResponseDataSchema>;
export type ErrorResponseDTO = z.infer<typeof ErrorResponseSchema>;

If the error is successfully parsed, I take the ExpressoTS specific content and put it into a custom error called "ResponseError". Here is the code for "ResponseError":

// utils\responseError.ts
import { BaseError } from "./baseError";
import { ErrorName } from "./baseError";

export class ResponseError extends BaseError<ErrorName> {}

"ResponseError" extends a generic "BaseError" class, which I will show below:

// utils\baseError.ts
export class BaseError<T extends string> extends Error {
  name: T;
  message: string;
  cause: any;

  constructor({
    name,
    message,
    cause,
  }: {
    name: T;
    message: string;
    cause?: any;
  }) {
    super();
    this.name = name;
    this.message = message;
    this.cause = cause;
  }
}

export type ErrorName = "RESPONSE_ERROR";

The "ErrorName" type has only one string value for now, but it can have multiple possible string values if I so desire. For example, I could do something like:

export type ErrorName = "RESPONSE_ERROR" | "CUSTOM_ERROR_2" | "CUSTOM_ERROR_3";

DeckView Page Part 2

Now that I've covered what the code for incrementing deck views, I can continue on to the next part of the "DeckView" Page.

// app\(primary)\deck\[id]\page.tsx
const { data: displayDeck, isLoading: isDeckLoading } =
  useQuery<DeckFindResponseDataDTO>({
    queryKey: ["deck", params.id],
    queryFn: () => FindDeck(params.id),
    retry: false,
    refetchOnWindowFocus: false, // Avoid refetch on window focus
    enabled: !!patchResponse, // Only run if PATCH request is successful
  });

const { data: deckSlots, isLoading: isDeckSlotsLoading } = useQuery<
  DeckslotFindResponseDTO[]
>({
  queryKey: ["deckSlots", params.id],
  queryFn: async () => {
    const response = await DeckSlotFindByDeckId(params.id);
    return response.deckslots || [];
  },
  retry: false,
  refetchOnWindowFocus: false, // Avoid refetch on window focus
  enabled: !!patchResponse, // Only run if PATCH request is successful
});

const updateDeckMutation = useMutation({
  mutationFn: FindDeck,
  onSuccess: (data) => {
    queryClient.setQueryData(["deck", params.id], data);
  },
});

const updateDeckSlotsMutation = useMutation({
  mutationFn: DeckSlotFindByDeckId,
  onSuccess: (data) => {
    queryClient.setQueryData(["deckSlots", params.id], data.deckslots || []);
  },
});

const toggleViewMode = () => {
  setViewMode((prev) => (prev === "en" ? "kr" : "en"));
};

The code for triggering the "FindDeck" and "DeckSlotFindByDeckId" functions is dependent on "IncrementDeckView" being successful. They fetch data for the deck and its deck slots. The "useMutation" hooks in this context are meant to refetch data when data mutation occurs (Ex: the user adds or deletes a card from their deck). As for "toggleViewMode", it toggles the displayed language between Korean and English, based on its current state.

DeckView Page Part 3

The final part of the "DeckView" page leverages loading and error states from the "useQuery" hooks to conditionally render the page.

// app\(primary)\deck\[id]\page.tsx
if (
  isPatchLoading ||
  isDeckLoading ||
  isDeckSlotsLoading ||
  isUserAuthenticated
) {
  return (
    <div className="flex w-full flex-1 flex-col items-center gap-20">
      <div className="w-full">
        <div className="py-6 text-center font-bold">Loading deck...</div>
      </div>
    </div>
  );
}

if (incrementViewError) {
  return (
    <div className="flex w-full flex-1 flex-col items-center gap-20">
      <div className="w-full">
        <div className="py-6 text-center font-bold">
          {incrementViewError.message}
        </div>
      </div>
    </div>
  );
}

const isOwner: boolean | null | undefined =
  userData && userData.id === displayDeck?.creator_id;

return (
  <div className="flex min-h-screen flex-col">
    <div className="flex-grow pb-32">
      <DeckInfo
        displayDeck={displayDeck}
        deckslots={deckSlots || []}
        onUpdate={() => updateDeckMutation.mutate(params.id)}
        isOwner={isOwner}
        viewMode={viewMode}
        setViewMode={setViewMode}
      />
      <div className="my-4 flex items-center justify-center space-x-2">
        {isOwner && <DeckPageDropDownMenu deckId={params.id} />}
        <Switch id="view-mode" onCheckedChange={toggleViewMode} />
        <Label htmlFor="view-mode">{viewMode === "en" ? "EN" : "KR"}</Label>
        {isOwner && <CardSearch deckId={params.id} viewMode={viewMode} />}
      </div>
      <DeckSlotDisplay
        deckslots={deckSlots || []}
        onUpdate={() => [
          updateDeckSlotsMutation.mutate(params.id),
          updateDeckMutation.mutate(params.id),
        ]}
        viewMode={viewMode}
        setViewMode={setViewMode}
        isOwner={isOwner}
      />
      <DeckPageFooter deckslots={deckSlots || []} />
    </div>
  </div>
);

Here is the page during loading:

Here is the page when an error occurs:

Here is the page when the page successfully loads:

For reference, this is what the DeckView Page used to look like in its "toy" version:

Conclusion

In this blog, we covered how to handle custom error responses using ExpressoTS, TanStack Query, and Next.js. By managing errors on both the backend and frontend, you can improve your app’s reliability and user experience. From backend error reporting to conditional rendering on the frontend, managing error states ensures your app is reliable. Thank you for reading, and I will see you in the next one!

Building a Deck-Building Site with ExpressoTS

Nicholas Tsang — Thu, 01 Aug 2024 18:54:18 +0000

If you've ever wondered what makes a deck-building site tick, you're in the right place. Today, we're taking a peak at the back end code, powered by the ExpressoTS framework, which has a few tricks up its sleeve to streamline the developer experience. This blog will showcase how I handle deck creation, request validation, and user authentication.

Let's start off with the Deck Creation controller.

//  ./src/deck/create/deck-create.controller.ts
import {
  Post,
  body,
  controller,
  request,
  response,
} from "@expressots/adapter-express";
import { BaseController, StatusCode, ValidateDTO } from "@expressots/core";
import { DeckCreateUsecase } from "./deck-create.usecase";
import cookieParser from "cookie-parser";
import { IDeckCreateRequestDto } from "./deck-create.dto";
import { Response, Request } from "express";
import { AuthSupabaseMiddleware } from "../../auth/supabase/auth-supabase.middleware";

@controller("/deck/create")
export class DeckCreateController extends BaseController {
  constructor(private deckCreateUsecase: DeckCreateUsecase) {
    super();
  }
  @Post(
    "",
    cookieParser(),
    ValidateDTO(IDeckCreateRequestDto),
    AuthSupabaseMiddleware
  )
  async execute(
    @body() payload: IDeckCreateRequestDto,
    @response() res: Response,
    @request() req: Request
  ): Promise<void> {
    return this.callUseCase(
      await this.deckCreateUsecase.execute(
        payload,
        req.headers["userid"] as string
      ),
      res,
      StatusCode.Created
    );
  }
}

To explain what is happening in the code: I am creating a controller class that handles requests from the client, validates its payload, and sends a response back to the client. The "BaseController" class that's being extended includes the "callUseCase" method, which is a helper function responsible for calling the use case that implements the business logic and returning a response to the front end. Within the route declaration, I'm using several middlewares: "cookieParser" for parsing cookies in the request, "ValidateDTO" to check if the request body matches the specified format (IDeckCreateRequestDto in this case), and "AuthSupabaseMiddleWare", which checks if the request is coming from a logged in user. Please note that ExpressoTS does not automatically install cookieParser. To install it and its type definitions, run the following commands:

npm i cookie-parser
npm i -D @types/cookie-parser

To perform DTO (Data Transfer Object) validation, I have to create a DTO class and define the variables in the class with decorators from the "class-validator" library. Here is the code for defining the structure of the request and response DTOs.

// ./src/deck/create/deck-create.dto.ts
import {
  IsIn,
  IsNotEmpty,
  IsOptional,
  IsString,
  IsUUID,
  MinLength,
} from "class-validator";
export class IDeckCreateRequestDto {
  @IsNotEmpty()
  @MinLength(3)
  @IsString({ message: "Name must be at least 3 characters long." })
  name: string;

  @IsOptional()
  @IsUUID()
  folder_id?: string | null;

  @IsOptional()
  @IsString({ message: "folder_id must be a string or empty" })
  description?: string | null;

  @IsIn(["public", "private", "unlisted"], {
    message: "Visibility must be either public, private, or unlisted",
  })
  visibility: "public" | "private" | "unlisted";
}

export interface IDeckCreateResponseDto {
  id: string;
  message: string;
}

Please note "class-validator" and "class-transformer" are needed for ExpressoTS' "ValidateDTO" method to work. ExpressoTS does not install them automatically. To install "class-validator" and "class-transformer", run the following commands:

npm install class-validator --save
npm install class-transformer --save

Here is the code for "AuthSupabaseMiddleWare":

// ./src/auth/supabase/auth-supabase.middleware.ts
import { NextFunction, Request, Response } from "express";
import { SupabaseProvider } from "./supabase.provider";
import { SupabaseClient } from "@supabase/supabase-js";
import { ISupabaseClientContext } from "./supabase.client.context";
import { container } from "../../app.container";

function getToken(req: Request): string | undefined {
  if (req.headers.authorization) {
    const authHeaderSplit = req.headers.authorization.split(" ");
    if (authHeaderSplit.length > 1 && authHeaderSplit[0] === "Bearer") {
      return authHeaderSplit[1];
    }
  }
  return undefined;
}

//Denies access to the route if the user is unauthorized.
export async function AuthSupabaseMiddleware(
  req: Request,
  res: Response,
  next: NextFunction
): Promise<void> {
  const supabaseProvider: SupabaseProvider = container.get(SupabaseProvider);
  const token = getToken(req);
  if (!token) {
    res.status(401).json({ error: "No authorization token." });
    return;
  }
  const context: ISupabaseClientContext = {
    reqCookies: req.cookies,
    res: res,
  };
  const supabase: SupabaseClient =
    supabaseProvider.createSupabaseClient(context);
  try {
    const {
      data: { user },
      error,
    } = await supabase.auth.getUser(token);

    if (error) throw error;

    req.headers["userid"] = user?.id;
    next();
  } catch (error) {
    res.status(401).json({ error: "Invalid token" });
  }
}

First, the code looks for a Bearer token that contains the access token from the client. If there is no access token, the request is denied, and an error is returned to the client. If a Bearer token is found, the code checks if it is valid with "supabase.auth.getUser(token)". Upon successful token validation, the user ID is passed to the request header. Otherwise, an invalid token error is sent to the client. You may have noticed that the code is able to instantiate an instance of a Supabase provider class with ExpressoTS' built in support for dependency injection:

const supabaseProvider: SupabaseProvider = container.get(SupabaseProvider);

This can be done because I've added a "@provide" decorator to my "SupabaseProvider" class. Here is the code for said class:

// ./src/auth/supabase/supabase.provider.ts
import { provide } from "inversify-binding-decorators";
import { SupabaseClient } from "@supabase/supabase-js";
import { createServerClient } from "@supabase/ssr";
import { ISupabaseClientContext } from "./supabase.client.context";
import { ENV } from "../../../src/env";

@provide(SupabaseProvider)
export class SupabaseProvider {
  public createSupabaseClient(context: ISupabaseClientContext): SupabaseClient {
    return createServerClient(
      ENV.SUPABASE.SUPABASE_URL!,
      ENV.SUPABASE.SUPABASE_PUBLIC_ANON_KEY!,
      {
        cookies: {
          get: (key) => {
            const cookies = context.reqCookies;
            let cookie: string = "";
            if (cookies) {
              cookie = cookies[key] ?? "";
            }
            return decodeURIComponent(cookie);
          },
          set: (key, value, options) => {
            if (!context.res) return;
            context.res.cookie(key, encodeURIComponent(value), {
              ...options,
              sameSite: "Lax",
              httpOnly: true,
            });
          },
          remove: (key, options) => {
            if (!context.res) return;
            context.res.cookie(key, "", { ...options, httpOnly: true });
          },
        },
      }
    );
  }
}

By adding the "@provide" decorator the "SupabaseProvider" class, I've binded it to a dependency injection container at Request Scope. Conveniently, if you create a project with the ExpressoTS CLI, it will set up the dependency injection container for you, saving you the hassle of having to do it yourself.

npm i -g @expressots/cli
expressots new <project-name>

Please note I'm using @supabase/ssr v0.3.0 and @supabase/supabase-js v2.43.5, so the code may not work for the latest versions of the aforementioned supabase packages.

Now that I've covered the controller, let's move on to the use case, where the business logic is defined:

// ./src/deck/create/deck-create.usecase.ts
import { provide } from "inversify-binding-decorators";
import {
  IDeckCreateRequestDto,
  IDeckCreateResponseDto,
} from "./deck-create.dto";
import { DeckRepository } from "../deck.repository";
import { DeckEntity } from "../deck.entity";
import { AppError, Report, StatusCode } from "@expressots/core";

@provide(DeckCreateUsecase)
export class DeckCreateUsecase {
  constructor(
    private deckRepository: DeckRepository,
    private newDeck: DeckEntity,
    private report: Report
  ) {}
  public async execute(
    payload: IDeckCreateRequestDto,
    userId: string
  ): Promise<IDeckCreateResponseDto | AppError> {
    try {
      this.newDeck.name = payload.name;
      this.newDeck.creator_id = userId;
      this.newDeck.folder_id = payload.folder_id;
      this.newDeck.description = payload.description;
      this.newDeck.visibility = payload.visibility;

      const res: DeckEntity | null = await this.deckRepository.create(
        this.newDeck
      );
      if (!res) {
        const error = this.report.error(
          "Failed to create deck.",
          StatusCode.BadRequest,
          "Failed to create deck."
        );
        throw error;
      }
      return {
        id: res.id,
        message: "Deck created successfully",
      };
    } catch (error: any) {
      console.log("Error occured during deck creation:");
      throw error;
    }
  }
}

Notice how I've added the "@provide" decorator to the "DeckCreateUsecase" class, which allows me to inject it as a dependency in the constructor for my "DeckCreateController" class. The "@provide" decorator has also been added to both the "DeckEntity" and "DeckRepository" classes (repositories are classes containing data access logic, such as Create, Read, Update, and Delete operations), which have been injected as dependencies in DeckCreateUsecase' constructor. To briefly explain what the use case does, it passes the request payload as a "DeckEntity" object (Entities are objects that are used to represent the data that is going to be manipulated by the application) to the "DeckRepository's" create method. If deck creation is successful, it returns a success response, and throws and error if deck creation failed.

Here is the code for the "DeckEntity" class:

// ./src/deck/deck.entity.ts
import { provide } from "inversify-binding-decorators";
import { IEntity } from "../base.entity";
import { v4 as uuidv4 } from "uuid";

@provide(DeckEntity)
export class DeckEntity implements IEntity {
  id: string;
  name?: string;
  creator_id?: string;
  username?: string;
  folder_id?: string | null;
  banner?: number | null;
  description?: string | null;
  views?: number;
  visibility?: string;
  created_at?: Date | null;
  updated_at?: Date | null;
  constructor() {
    this.id = uuidv4();
  }
}

Here is the code for "DeckRepository":

// ./src/deck/deck.repository.ts
import { deckTable } from "../supabase/migrations/schema";
import { DeckEntity } from "./deck.entity";
import { BaseRepository } from "../base-repository";
@provide(DeckRepository)
export class DeckRepository extends BaseRepository<DeckEntity> {
  constructor() {
    super();
    this.table = deckTable;
  }
}

The "create" method isn't actually defined within the "DeckRepository" class. Instead, it is inherited from the "BaseRepository" class. The "DeckRepository" class merely defines which table ("deckTable" in this case) will be used for data insertion. The table schema can be found below:

// ./src/supabase/migrations/schema.ts
import {
  pgTable,
  index,
  unique,
  integer,
  text,
  timestamp,
  uuid,
  primaryKey,
  uniqueIndex,
} from "drizzle-orm/pg-core";
export const deckTable = pgTable(
  "deck",
  {
    id: uuid("id").primaryKey().notNull(),
    name: text("name").unique().notNull(),
    creator_id: uuid("creator_id")
      .notNull()
      .references(() => userTable.id, { onDelete: "cascade" }),
    folder_id: uuid("folder_id").references(() => deckFolderTable.id, {
      onDelete: "cascade",
    }),
    banner: integer("banner").references(() => cards.id, {
      onDelete: "set null",
    }),
    description: text("description"),
    views: integer("views").notNull().default(0),
    visibility: text("visibility").notNull().default("public"),
    created_at: timestamp("created_at", { withTimezone: true })
      .defaultNow()
      .notNull(),
    updated_at: timestamp("updated_at", { withTimezone: true })
      .defaultNow()
      .notNull(),
    name_lower: text("name_lower"),
  },
  (table) => ({
    nameIndex: uniqueIndex("unique_name_case_insensitive").on(
      sql`lower(${table.name})`
    ),
    trgm_idx_deck_name: index("trgm_idx_deck_name").using(
      "gin",
      table.name_lower
    ),
    deck_name_unique: unique("deck_name_unique").on(table.name),
  })
);

As you may have guessed, I'm using Drizzle to help define the table schema.
As for the create method in the "BaseRepository" class, the code can be found below:

// ./src/base-repository.ts
import "reflect-metadata";
import { IEntity } from "./base.entity";
import { DrizzleProvider } from "./db/drizzle/drizzle.provider";
import { container } from "./app.container";
import { provide } from "inversify-binding-decorators";
import { IBaseRepository } from "./base-repository.interface";
import { NodePgDatabase } from "drizzle-orm/node-postgres";
import { PgTableWithColumns } from "drizzle-orm/pg-core";

@provide(BaseRepository)
export class BaseRepository<T extends IEntity> implements IBaseRepository<T> {
  protected db: NodePgDatabase<Record<string, never>>;
  protected table: PgTableWithColumns<any>;

  constructor() {
    this.db = container.get(DrizzleProvider).Drizzle;
  }

  async create(item: T): Promise<T | null> {
    try {
      const res = await this.db
        .insert(this.table)
        .values(item)
        .returning({ id: this.table.id });
      return res[0] as T;
    } catch (error) {
      console.log("error occured while creating: ");
      console.log(error);
      return null;
    }
  }
}

The "create" method inserts the values defined in the item parameter into the table, which was defined in the constructor of the "DeckRepository" class. It then returns the ID of the newly created row upon a successful insertion, or null upon a failed insertion. The "DrizzleProvider" class establishes a connection to my PostGres database using Drizzle ORM and a singleton instance of a PostGres pool:

// ./src/db/drizzle/drizzle.provider.ts
import { provideSingleton } from "@expressots/core";
import { NodePgDatabase, drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import { postgres_pool_config } from "./postgres/postgresDB";

/**
 * Provider to inject the database pool into the container.
 */

@provideSingleton(DrizzleProvider)
export class DrizzleProvider {
  private pool: Pool | null = null;
  private db: NodePgDatabase<Record<string, never>> | null = null;

  private constructor() {}
  private initPool(): void {
    if (!this.pool) {
      this.pool = new Pool(postgres_pool_config);
      console.log("Pool created");
    } else {
      // console.log("Pool already exists");
    }
    // console.log(pool)
  }

  public get Pool(): Pool {
    this.initPool();
    return this.pool;
  }

  public get Drizzle(): NodePgDatabase<Record<string, never>> {
    this.initPool();
    if (!this.db) {
      this.db = drizzle(this.pool);
      console.log("Drizzle created");
    } else {
      // console.log("Drizzle already exists");
    }
    // console.log(db)
    return this.db;
  }

  public get closePool(): boolean {
    try {
      if (this.pool) {
        this.pool.end();
        console.log("Pool closed");
      }
    } catch (error) {
      console.log("Error while closing pool");
      console.log(error);
      return false;
    }
    return true;
  }
}

The "postgres_pool_config" parameter contains the configuration settings for instantiating a PostGres pool. The code for "postgres_pool_config" is defined below:

// ./src/db/drizzle/postgres/postgresDB.ts
import { ENV } from "../../../../src/env";
/**
 * Configuration of the database pool.
 */
export const postgres_pool_config = {
  host: ENV.DB.DB_HOST,
  port: ENV.DB.DB_PORT,
  user: ENV.DB.DB_USER,
  password: ENV.DB.DB_PASSWORD,
  database: ENV.DB.DB_NAME,
};

You may have noticed I'm not directly calling environment variables with process.env, but with a custom "env.ts" file instead. This allows developers to call environment variables with spell checking, which is not possible with process.env.

My "env.ts" file is defined below:

// ./src/env.ts
export const ENV = {
  CORS: {
    FRONTEND_ORIGIN: String(process.env.FRONTEND_ORIGIN || "localhost:3000"),
  },
  DB: {
    DATABASE_URL: String(process.env.DATABASE_URL),
    DB_HOST: String(process.env.DB_HOST),
    DB_NAME: String(process.env.DB_NAME),
    DB_PORT: Number(process.env.DB_PORT),
    DB_USER: String(process.env.DB_USER),
    DB_PASSWORD: String(process.env.DB_PASSWORD),
  },
  SUPABASE: {
    SUPABASE_URL: String(process.env.SUPABASE_URL),
    SUPABASE_PUBLIC_ANON_KEY: String(process.env.SUPABASE_PUBLIC_ANON_KEY),
  },
};

By leveraging ExpressoTS, I was able to streamline the development process with its organized structure and dependency injection capabilities. We explored how controllers handle incoming requests, validate payloads, and ensure secure user authentication with Supabase. Additionally, we delved into the use case layer where business logic is implemented and entities are manipulated, followed by the repository layer responsible for data access. Finally, I utilized Drizzle ORM to interact with my PostgreSQL database. I hope you enjoyed this quick rundown of the back end code, and I hope to see you in the next blog!

Baking Up the Moxfield of Cookie Run: Braverse

Nicholas Tsang — Thu, 04 Jul 2024 20:56:56 +0000

Hey gamers! As a deck-building enthusiast, I got hooked on Cookie Run: Braverse after my first match, But there are no English deck-building sites! So, I plan on creating one for the community. Check out my blog for details!

🔗 https://nicktsan.com/blog/initial-buildspace-blog