DEV Community: ExpressoTS

NPM Shield

Richard Zampieri — Mon, 17 Mar 2025 21:23:50 +0000

🚀 Introducing NPM Shield – Secure Dependencies 🛡️

Two months ago, we launched Better NPM. Since then, we've received numerous feature requests, UI improvement suggestions, and valuable feedback—including constructive criticism. We listened carefully, tested the waters, and understood developers' needs regarding dependency management, security, detailed package insights, and robust analytics.

Today, we're excited to announce the next evolution—now rebranded as NPM Shield!

Why NPM Shield? Because it reflects our commitment to protecting your projects through transparency, robust analytics, and comprehensive security.

Here's what's new and improved:

✅ Advanced Security Scans – Instantly identify vulnerabilities and risks across your entire dependency tree (CVE and CVSS).
✅ Detailed Package Insights – Gain deeper visibility into maintenance, adoption, and community health of your dependencies.
✅ Dependency Tree Graphs – Visualize your project's dependencies clearly and intuitively.
✅ Risk Mitigation Tools – Proactively address and fix dependency risks before they affect your project.

🔗 Check it out here: NPM Shield

A huge thank you to the community for your invaluable feedback. Your insights have shaped NPM Shield, helping us build a smarter, safer, and more transparent package ecosystem.

💬 We're eager to hear your thoughts on NPM Shield—your feedback drives continuous improvement!

Let's build secure, reliable software together. 💪

Our LinkedIn

Better NPM

Richard Zampieri — Wed, 19 Feb 2025 08:27:14 +0000

🚀 Reimagining NPM: A Smarter, More Secure Package Ecosystem

🌐 Better NPM

Package managers—from npm to vcpkg, Conan, Cargo, nuget-dotnet, pip, Maven, and beyond—often fail to give you a complete view of a package before you add it to your project. In today’s rapidly expanding (and often insecure) internet, developers need better tools and insights to ensure that each dependency they bring in is secure, well-maintained, and widely adopted.

Many organizations take security seriously, yet still rely on patchwork solutions that small companies often can’t afford. That’s why we built a lightweight layer on top of NPM—we’re calling it Better NPM – ExpressoTS Store—to deliver a comprehensive view of every package you consider. This includes data on security breaches, maintenance status, and adoption rates. We’re also focusing on providing ecosystem-wide details that help you scan your project, spot potential vulnerabilities, and make truly informed decisions when selecting dependencies. (SCAN in development)

Why Better NPM – ExpressoTS Store?

✅ Transparency: Gain rich insights into package security, maintenance activity, and adoption statistics.
✅ ExpressoTS Plugin Hub: Discover all plugins built for the ExpressoTS Framework in one place.
✅ Better Analytics for Maintainers: Understand how packages are used and receive feedback on how to improve them (feature in development).
✅ A Unified Marketplace: A central hub for vetted plugins and extensions, ensuring consistency and quality.

🔐 Security at the Core: Stop scavenging GitHub issues and third-party tools. Our goal is to arm you with detailed security info up front, so you can focus on building rather than endlessly verifying.

Want to know more?

📩 Reach out our Tech Evangelist: https://www.linkedin.com/in/umataldetatiana/

🚀 Check out our very beta store: https://lnkd.in/gGKMHzN6
Let’s build a better, smarter package ecosystem together! 💡

3.0 is Here!

Richard Zampieri — Thu, 05 Dec 2024 18:21:47 +0000

ExpressoTS v3.0 is Here! 🎉

This major update brings significant enhancements to ExpressoTS Framework.

Reduced Dependencies: Streamlined for lighter and faster applications.
Custom IoC Container
Embedded Environment Management: Now built into the framework for simplicity.
New @expressots/shared Package: Consolidates utilities for modular development.
Micro API Template: Quickly prototype microservices for enhanced scalability.
Streamlined Application Structure: Centralized configuration in app.ts for easier maintenance.
Rendering Engine Support: Use EJS, Handlebars, Pug, and more via plugins.
Plugin System: Extend functionality effortlessly with custom plugins.
CLI Improvements: Enhanced commands, performance boosts, supporting npm, yarn, and pnpm.
Improved Testing: Migrated to Jest with extensive unit tests and high coverage. Thanks to Early AI
Improved security score, thanks to Snyk Health Package Extension

For more information checkout the full article here!

"How the Open Source Project Uses EarlyAI to Enhance Framework Code Quality"!

Richard Zampieri — Mon, 04 Nov 2024 16:52:12 +0000

Join us on November 12 for an exclusive webinar:

In this webinar, Richard Zampieri ( @rsaz ) and Sharon Barr will share how EarlyAI is used by @ExpressoTS to generate high coverage, quality unit tests in a click.

ExpressoTS’s approach focuses on more than just code coverage; it’s about gaining rapid insights to improve code quality directly through unit tests generated by EarlyAI. This tool acts as both a time-saver and a proactive bug detector, helping developers quickly identify areas for enhancement.

Don’t miss out on this chance to see how EarlyAI can transform the future of software development!

📅 Date: Tuesday, November 12
⏰ Time: 11am PST | 2pm EST | 9pm IL
🔗 Register: https://lnkd.in/dTsnNrBu

ExpressoTS surpassed AdonisJs

Richard Zampieri — Mon, 09 Sep 2024 20:04:13 +0000

🚀 Exciting Milestone Alert! 🚀

ExpressoTS has surpassed AdonisJS in weekly downloads after just 1.5 years! 🎉 We're quickly becoming the go-to framework for #NodeJS & #TypeScript devs.

Full details here

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!

ExpressoTS on The Rise???

Richard Zampieri — Sun, 28 Jul 2024 03:22:23 +0000

Hi Dev Community,

Over the past 3 to 4 weeks, we've observed a noticeable increase in downloads of the ExpressoTS framework. Let’s hope this upward trend continues! 🥂

Thank you for your contributions, engagement, and feedback. Your efforts have been instrumental in enhancing the platform and creating a better developer experience.

Best,

ExpressoTS Render Engine

Richard Zampieri — Tue, 23 Jul 2024 08:19:46 +0000

Render Engine

ExpressoTS enhances the web server capabilities of Express.js by providing a streamlined experience for rendering views. ExpressoTS supports various render engines out-of-the-box, including EJS, PUG, and Handlebars (HBS). This makes it easy for developers to start rendering views without needing additional configuration, as default settings are provided for each supported engine.

Supported Render Engines

ExpressoTS supports the following render engines:

EJS
PUG
HBS (Handlebars)

Handlebars Configuration Options

export type HandlebarsOptions = {
    viewEngine?: string; // The view engine to be used
    viewsDir?: string; // The path to the views folder
    partialsDir?: string; // The path to the partials folder
};

Default Handlebars configuration options

{
    viewEngine: "hbs",
    viewsDir: <root>/views,
    partialsDir: <root>/views/partials,
}

Default Folder structure

Default folder structure for Handlebars:

src
views
|--partials
|   |--partial.hbs
|--index.hbs

All other engines follow the same structure, with the exception of the partials folder, which is specific to Handlebars.

Handlebars File Example

<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>HBS Example</title>
    </head>
    <body>
        <h1>Hello from HBS</h1>
        <p>Render partial: {{> partial}}</p>
    </body>
</html>

Other Engine Configuration Options

Pug Configuration Options

export type PugOptions = {
    viewEngine?: string;
    viewsDir?: string;
};

Default Pug configuration options

{
    viewEngine: "pug",
    viewsDir: <root>/views,
}

EJS Configuration Options

export type EjsOptions = {
    viewsDir?: string;
    viewEngine?: string;
    serverOptions?: EjsOptionsServer;
};

Default EJS configuration options

{
    viewEngine: "ejs",
    viewsDir: <root>/views,
    serverOptions: {
        cache: true,
        compileDebug: false,
        debug: false,
        delimiter: "%",
        strict: false,
    },
}

How to use

Here's how you can set up ExpressoTS to use a render engine like HBS (handlebars) in your application:

In the app.provider configuration provider, you can set the render engine:

export class App extends AppExpress {
    private middleware: IMiddleware;
    private provider: ProviderManager;

    constructor() {
        super();
        this.middleware = container.get<IMiddleware>(Middleware);
        this.provider = container.get(ProviderManager);
    }

    protected configureServices(): void {
        // Set the render engine to HBS
        this.setEngine(Engine.HBS);

        this.middleware.setErrorHandler();
    }

    protected async postServerInitialization(): Promise<void> {
        if (this.isDevelopment()) {
            this.provider.get(Env).checkAll();
        }
    }

    protected serverShutdown(): void {}
}

If you want to pass custom options to the render engine, you can do so by passing an object with the desired options to the setEngine method. For example, to set the views directory to a custom path, you can do the following:

this.setEngine<HBS>(Engine.HBS, { viewsDir: <<custom-path>> });

How To Render Views in ExpressoTS

To render a view in ExpressoTS, you can use the render method provided by the Response object. Here's an example of how you can render a view in ExpressoTS:

@Get("/")
root(@response() res: Response) {
    res.render("index", { date: new Date(), name: "Random information" });
}

In the example above, the render method is called on the Response object, passing the name of the view to be rendered and an object with data to be passed to the view. The view engine will render the view with the provided data and return the rendered HTML to the client.

Render Decorator

The @Render decorator can be used on controller methods to render views using the specified view engine. Here's an example of how you can use the @Render decorator to render a view in ExpressoTS:

Rendering passing the view and default data in the decorator

@Get("/")
@Render("index", { date: new Date(), name: "Random information" })
root() {}

Rendering passing only the view in the decorator

@Get("/")
@Render("index")
root() {
    return { date: new Date(), name: "Random information" };
}

Happy Coding! 🐎

ExpressoTS - DB in Memory

Richard Zampieri — Sat, 06 Jul 2024 05:16:36 +0000

Explore our In-Memory DB in action! 🐎

This straightforward class enables developers to prototype APIs effortlessly, eliminating the need to connect to or set up database. Perfect for rapid development and testing!

E2E Testing with ExpressoTS and SuperTest

Richard Zampieri — Fri, 26 Apr 2024 08:53:53 +0000

Intro

Supertest is a popular npm library commonly used for testing HTTP servers and APIs. It works seamlessly with Node.js HTTP servers, including those created with frameworks like Express. Supertest provides a high-level abstraction for testing HTTP, allowing you to make requests to your application and assert the responses.

Purpose

Supertest is designed to simplify the process of sending simulated HTTP requests to a server and verifying the responses. It is primarily used in the context of writing tests, often in combination with testing frameworks like Jest, Mocha, or Jasmine. The library's main purpose is to enable developers to write concise tests for their APIs, ensuring that the endpoints function as expected under various conditions.

Pros

Ease of Use: Supertest provides a fluent, chainable API that makes it easy to write readable and expressive tests.
Integration: It integrates smoothly with popular testing frameworks like Mocha, Jest, and others, allowing you to use familiar assertion styles and test management features.
Flexibility: You can test both local and remote servers, making it useful for a variety of testing scenarios including integration and acceptance testing.
No Server Startup Required: When testing Node.js HTTP servers (like Express apps), Supertest can directly invoke the server's request handling code without needing to listen on a network port. This makes tests faster and easier to manage in a development environment.
Response Assertions: Supertest supports a wide range of HTTP assertions, such as checking status codes, header fields, and response bodies, which helps in validating API responses thoroughly.

Cons

Limited to HTTP: It is designed specifically for HTTP API testing. If your application logic is not exposed over HTTP or requires more complex interaction (like WebSockets or other protocols), Supertest will not be suitable.
Asynchronous Complexity: Like any tool that performs I/O operations, tests written with Supertest are inherently asynchronous. This can complicate test code, especially for beginners or in complex scenarios requiring multiple asynchronous steps.
Error Handling: Error handling in asynchronous tests can be tricky, and Supertest’s error messages can sometimes be vague, which might complicate debugging efforts.
Environment Mocking: While Supertest is great for testing the real responses from your server, you might still need to set up and tear down test environments or mock external services, which could require additional tools or libraries.

Integration with ExpressoTS

To help you on developing your E2E testing to verify your endpoints we fully integrated ExpressoTS Application with Supertest, making it easy to setup the test and validate the entire process from application bootstrap to make a http method request call to your endpoint and validate the response back.

Here is an example:

ExpressoTS application bootstrap

async function bootstrap() {
    const app = await AppFactory.create(container, App);
    app.listen(3000, ServerEnvironment.Development);
}

Endpoint for testing

@controller("/organization")
export class OrganizationController {
    @Post("")
    async create(
        @body() organization: IOrganizationRequestDto,
        @response() res: express.Response,
    ) {
        return res.status(StatusCode.Created).json(organization);
    }
}

The Test Setup

import "reflect-metadata";

import { ServerEnvironment } from "@expressots/adapter-express";
import { AppFactory, StatusCode } from "@expressots/core";
import express from "express";
import request from "supertest";
import { container } from "../src/app.container";
import { App } from "./../src/app.provider";

const appExpress = express();

describe("api test", () => {
    let server: express.Application;

    beforeAll(async () => {
        const appInstance = await AppFactory.create(container, App);
        await appInstance.listen(3000, ServerEnvironment.Development);

        server = await appInstance.getHttpServer();
    });

    describe("organization.module", () => {
        test("POST /organization", async () => {
            const newOrg = {
                name: "test org",
            };

            const response = await request(server)
                .post("/organization")
                .send(newOrg);

            expect(response.status).toBe(StatusCode.Created);
            expect(response.body).toEqual(newOrg);
        });
    });
});

Results

Happy coding!

Nestjs x ExpressoTS @param transformation

Richard Zampieri — Thu, 25 Apr 2024 09:10:14 +0000

The ExpressoTS Adapter provides essential resources for the Express.js platform, including decorators. We've recently released an enhancement to the adapter that addresses a subtle but critical issue you might not notice until it becomes a problem.

In TypeScript, parameters from URL paths (e.g., :id in Express.js routes) are passed as strings, even if they represent numbers. This behavior is standard across many web frameworks, including Express.js.

Here’s how you typically handle this in your code:

// Controller
@Get("/:id")
    findOne(@param("id") id: number) {
        return this.userUseCase.findOne(Number(id));
    }

// Use Case
findOne(id: number) {
        return this.db.users.find((user) => user.id === id);
    }

// DB
const users = [
        {
            id: 1,
            name: "Alice Smith",
            email: "alice@example.com",
            role: "Admin",
        },
        {
            id: 2,
            name: "Bob Johnson",
            email: "bob@example.com",
            role: "Regular",
        }
]

Directly comparing the id from the request without converting it to a number can lead to unexpected results due to type mismatches.

In contrast, NestJS uses Binding Pipes to handle this conversion. This method involves passing data through multiple layers for conversion, requiring developers to be familiar with the necessary pipes.

.NET Core simplifies this process by using annotations to automatically convert types based on the variable receiving the parameter.

At ExpressoTS, we've streamlined this process even further. Our @param decorator not only converts the parameter but also validates it against the expected type of the receiving variable. This approach enhances efficiency and intuitiveness. Here's how it looks:

@Get("/:id")
    findOne(@param("id") id: number) {
        return this.userUseCase.findOne(id);
    }

The id parameter is automatically converted from a string to a number, eliminating the common error of undefined results when comparing different types and you don't need to memorize pipes to convert your parameter to the desired type, that should work out-of-the box.