As we've seen in the previous article, there's a small inconvenient with Prisma ORM that we'll solve by rewriting it entirely (cause who doesn't want another npm package) We'll go step by step, explaining how things work thus this series of post might be a bit long.
In our process of creating an ORM, we will create StORM, which stands for Storm Object Relational Mapping or Storm ORM. It will be open source and located in this repository.
That being said, let's start 🌪️
PostgreSQL Database
First, we need a database to query. I'll use Docker to run one locally with one command. I set simple credentials since it is for local development but feel free to override them.
docker run --name storm-test-db \
-e POSTGRES_PASSWORD=storm-pass \
-e POSTGRES_USER=storm-user \
-e POSTGRES_DB=storm-database \
-p 5432:5432 -d postgres:15.2-alpine
Once this command is successful, you should have a database running on your port 5432. The connection URL should be something like this :
postgres://storm-user:storm-pass@localhost:5432/storm-database
Database Tables
The database is running, now let's add a few tables so we can build the library before having to create a migration system.
Suppose we were working on a simple CMS, we would need to create 3 tables: Users, Posts and CoverImages. Tables are linked together so that users have several posts, and each post has a single cover image.
We can write SQL queries to create each table with a bunch of properties like this:
Users
CREATE TABLE IF NOT EXISTS users (
id SERIAL PRIMARY KEY,
username VARCHAR(100) NOT NULL,
created_at timestamp NOT NULL,
updated_at timestamp NOT NULL
);
Posts
CREATE TABLE IF NOT EXISTS posts (
id SERIAL PRIMARY KEY,
name VARCHAR(255) NOT NULL,
user_id INT,
publication_date timestamp NOT NULL,
created_at timestamp NOT NULL,
updated_at timestamp NOT NULL,
FOREIGN KEY (user_id) REFERENCES users (id)
);
CoverImages
CREATE TABLE IF NOT EXISTS cover_images (
id SERIAL PRIMARY KEY,
url VARCHAR(255) NOT NULL,
post_id INT UNIQUE,
created_at timestamp NOT NULL,
updated_at timestamp NOT NULL,
FOREIGN KEY (post_id) REFERENCES posts (id)
);
Running the scripts
We need to send these queries to our database and we'll again use Docker to connect to PostgreSQL inside the container.
docker exec -it storm-test-db psql -U storm-user -W storm-database
This should ask you for the password we used to create the database, then you can paste the 3 SQL queries in order and execute them. Finally, type exit to close the terminal.
Node.Js Typescript Project
Now that our database is set up we can init the typescript project for our lib. Pretty simple and straight-forward instructions with pnpm, notice that you can use npm or yarn as well.
# init nodejs typescript project
pnpm init
pnpm i -D tsc typescript @types/node
pnpm tsc --init --outDir dist
touch index.ts
Next, we need to add a few libraries to be used in our project. We will also create a .env file that will hold our environment variables, specifically our database URL.
pnpm i pg dotenv
pnpm i -D @types/pg
# file : .env
DATABASE_URL=postgres://storm-user:storm-pass@localhost:5432/storm-database
We will also add vitest for Test-Driven-Development and create a vitest.config.ts file.
pnpm i -D vite vitest
mkdir tests
touch vitest.config.ts tests/index.ts
// file : vitest.config.ts
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
dir: "tests",
include: ["**/*.spec.ts"],
environment: "node",
passWithNoTests: true,
},
});
The last step of our setup is updating our package.json with these lines:
"main": "dist/index.js",
"scripts": {
"build": "tsc",
"start": "node dist/index.js",
"dev": "npm run build && npm run start",
"test": "vitest"
},
Our first test
To finish our setup, let's create a simple test. Communicating with our database requires us to have its URL so our first test will make sure that we have it in our environment.
First, we create a src directory and an index.ts file inside it.
We need a class that checks our process.env for the DARABASE_URL variable. We will use dotenv to populate the process.env.
// file: src/index.ts
import Dotenv from "dotenv";
import pg from "pg";
Dotenv.config();
class StormClient {
private connectionString: string;
constructor() {
const connectionString = process.env.DATABASE_URL;
if (!connectionString) {
throw new Error("No connection string provided");
}
this.connectionString = connectionString;
}
}
export default StormClient;
For the tests, the stubEnv helper provided by vitest will allow us to mock the content of the process.env.
// file: tests/index.spec.ts
import { describe, it, expect, afterEach, vi } from "vitest";
import StormClient from "../src/index";
describe("Check connection strihng", () => {
it("should use the connection string provided in the environment", () => {
// Make sure the environment variable is set to some value
const url = "postgres://dummy_url:5432/storm";
vi.stubEnv("DATABASE_URL", url);
// Create a new instance of the client and check the connection string
const client = new StormClient();
expect(client["connectionString"]).toBe(url);
});
it("should throw an error if no connection string is provided", () => {
// Delete the environment variable
vi.stubEnv("DATABASE_URL", "");
// Ensure that an error is thrown when creating a new instance
expect(() => new StormClient()).toThrow("No connection string provided");
});
afterEach(() => {
vi.unstubAllEnvs();
});
});
Let's run our tests
pnpm test
If the tests run successfully you should have a result like this:
> storm@1.0.0 test /[...]/storm
> vitest
RUN v0.31.4 /[...]/storm
✓ tests/index.spec.ts (2)
Test Files 1 passed (1)
Tests 2 passed (2)
...
What's next
The project setup is done. You can find the whole code for this article here. In the next article, we'll connect to our database and start implementing a few methods on the client. See you then 👋