Forem: Jean Carlos Taveras

Sequelize + TypeScript - What you need to know

Jean Carlos Taveras — Mon, 08 Mar 2021 05:38:10 +0000

Hi Dev community 👋🏾!

I just decided that I want to write a post so here I AM. I didn't know what to write about and I landed on the idea of Sequelize + TypeScript my experience working with Sequelize and adding TypeScript to it.

Table of Content

A Little bit of Background
Setup Sequelize
Setup Sequelize Models
Adding Model Association
Conclusion

A Little bit of Background

So the idea came from a project that I was managing and the client decided that they wanted the project handed in yesterday (as usual), so the company put together a small group of Jr. Engineers plus me as the Senior/Lead Engineer so I would be in charge of choosing the stack so I took the decision of using:

Express/NodeJS (Backend)
PostgreSQL (Database)
Plain React (Frontend)
Sequelize (ORM)

Since any of the Jr. Engineers had any experience developing on TypeScript nor working on a microservices-based architecture I decided that it would be good for us to use plained JS and monolithic architecture since that what they knew at the moment and I didn't want to slow down the project.

Now I hear you asking what does this have to do with Sequelize + TypeScript? Well, everything. The company decided to use the project as a base ground for another project and it's here when we noticed all the limitations and problems that we have with the current setup. Just to name a few:

A lot of duplicated code both in the Backend and the Frontend
Slow dev environment
Weird bugs that cause the project to crash
It was hard to understand what is doing what
Database Models were messy
And more...

So here I'm refactoring the project using TypeScript and setting up a Microservice-based architecture with Event-Based Communication (as it should) while my team is working on bug fixes and waiting for me to be done with the refactoring.

Well enough talking let's dive in and set up Sequelize to use TypeScript.

Setup Sequelize

I'll be using the sequelize-cli tool which generates the Sequelize folder structure and configuration based on the .sequelizerc file which should look like this

const path = require('path');

module.exports = {
  config: path.resolve('.', 'config.js'),
  'models-path': path.resolve('./db/models'),
  'seeders-path': path.resolve('./db/seeders'),
  'migrations-path': path.resolve('./db/migrations')
};

You can now run npx sequelize-cli init and you will have the following project structure

- config.js
- db/
  - migrations/
  - models/
    - index.js
  - seeders/

Your db/models/index.js file will look like this

'use strict';

const fs = require('fs');
const path = require('path');
const Sequelize = require('sequelize');

const basename = path.basename(__filename);
const env = process.env.NODE_ENV || 'development';
const config = require('../../app/config')[env];
const db = {};

let sequelize;
if (config.url) {
  sequelize = new Sequelize(config.url, config);
} else {
  // another sequelize configuration
}

fs.readdirSync(__dirname)
  .filter(file => {
    return (
      file.indexOf('.') !== 0 && file !== basename && file.slice(-3) === '.js'
    );
  })
  .forEach(file => {
    const model = sequelize['import'](path.join(__dirname, file));
    db[model.name] = model;
  });

Object.keys(db).forEach(modelName => {
  if (db[modelName].associate) {
    db[modelName].associate(db);
  }
});

db.sequelize = sequelize;
db.Sequelize = Sequelize;

module.exports = db;

Yeah, a bunch of code, but this essentially eases the use of models and reduces the amount of requires/imports that you'd do in your models in the future.

Pretty cool stuff, but I want to use TypeScript I hear you say. Ok so let's change our first file to TypeScript. Rename the index.js file to index.ts and let's change some things in it

import { Sequelize } from 'sequelize';

const env = process.env.NODE_ENV || 'development';
const config = require(__dirname + '/../../config.js')[env];

const  sequelize = config.url
  ? new Sequelize(config.url, config)
  : new Sequelize(config.database, config.username, config.password, config);

export { Sequelize, sequelize };

Yup, that's it!

Ok, let me explain why we removed a bunch of code from the file, and the reason is due to TypeScript being TypeScript. I just didn't want to type the db Object that is being generated based on the files inside the models/ directory. So we removed all of that and just exported Sequelize (Class) and sequelize (instance). The sequelize instance has a reference to the database connection so when we create our models we use this instance so we can communicate with the database through the models.

The first file is done and a bunch more to go.

Setup Sequelize Models

If we were to use JS a Sequelize model would look like this.

NOTE: I'll be declaring two example models: Author, and Book.

Let's first see how to add a Sequelize Model using JS. The Author Model would look like the following

// /models/author.js
module.exports = (sequelize, DataTypes) => {
  const Author = sequelize.define(
    'Author',
    {
      id: {
        allowNull: false,
        autoIncrement: false,
        primaryKey: true,
        type: DataTypes.UUID,
        unique: true,
      },
      firstName: {
        allowNull: true,
        type: DataTypes.TEXT,
      },
      lastName: {
        allowNull: false,
        type: DataTypes.TEXT,
      },
      email: {
        allowNull: true,
        type: DataTypes.TEXT,
      },
    },
    {}
  );

  return Author;
};

So let's give the TypeScript treat to the Author model as well. Change the name to author.ts and let's define some interfaces

import { Model, Optional } from 'sequelize';

interface AuthorAttributes {
  id: string;
  firstName: string;
  lastName: string;
  email: string;
};

/*
  We have to declare the AuthorCreationAttributes to
  tell Sequelize and TypeScript that the property id,
  in this case, is optional to be passed at creation time
*/
interface AuthorCreationAttributes
  extends Optional<AuthorAttributes, 'id'> {}

interface AuthorInstance
  extends Model<AuthorAttributes, AuthorCreationAttributes>,
    AuthorAttributes {
      createdAt?: Date;
      updatedAt?: Date;
    }

We need these interfaces to tell TypeScript which properties an author instance has.

Now let's define the Author Model in the TS way

// model/author.ts
import { sequelize } from '.';

// ... instances code

const Author = sequelize.define<AuthorInstance>(
  'Author',
  {
    id: {
      allowNull: false,
      autoIncrement: false,
      primaryKey: true,
      type: DataTypes.UUID,
      unique: true,
    },
    firstName: {
      allowNull: true,
      type: DataTypes.TEXT,
    },
    lastName: {
      allowNull: false,
      type: DataTypes.TEXT,
    },
    email: {
      allowNull: true,
      type: DataTypes.TEXT,
    },
  }
);

Now you should be wondering, why do I have to go through all of that if I'll end up doing the same? Well, if you made a typo on any property of the model define object, TypeScript will yell at you and tell you that the property X is missing, same if you try to add a property that is not defined on the AuthorAttributes interface TypeScript will tell you that property Y is not defined on type AuthorAttributes

Now that we know how to declare a Sequelize model using TypeScript let's define the book.ts model.

// /models/book.ts
import { Model, Optional } from 'sequelize';
import { sequelize } from '.';

interface BookAttributes {
  id: string;
  title: string;
  numberOfPages: number;
  authorId: string;
}

interface BookCreationAttributes
  extends Optional<BookAttributes, 'id'> {}

interface BookInstance
  extends Model<BookAttributes, BookCreationAttributes>,
    BookAttributes {
      createdAt?: Date;
      updatedAt?: Date;
    }

const Book = sequelize.define<BookInstance>(
  'Book',
  {
    id: {
      allowNull: false,
      autoIncrement: false,
      primaryKey: true,
      type: DataTypes.UUID,
      unique: true,
    },
    title: {
      allowNull: true,
      type: DataTypes.TEXT,
    },
    numberOfPages: {
      allowNull: false,
      type: DataTypes.INTEGER,
    },
    authorId: {
      allowNull: true,
      type: DataTypes.UUID,
    },
  }
);

export default Book;

That's it! That's how you define a Sequelize Model using TypeScript.

Adding Model Association

If you want to add associations to the model let's say An Author HAS MANY Books then in JS you'd do something like this

// model/author.js
  Author.associate = models => {
    Author.hasMany(models.Book, {
      foreignKey: 'authorId',
    });
  };

// model/book.js
  Book.associate = models => {
    Book.belongsTo(models.Author, {
      foreignKey: 'id'
    });
  };

So do you remember when I said that the code generated when we ran npx sequelize-cli init will help us when trying to do requires/imports? That time has come!

Sequelize will try to run the associate function if defined and will add the defined associations to the Models.

But we are here for TypeScript not for JS, so how do we do this in our defined models in TypeScript? Let's see how.

// models/author.ts
import Book from './book';

// ... Code Defining the Author Model

Author.hasMany(Book, {
  /*
    You can omit the sourceKey property
    since by default sequelize will use the primary key defined
    in the model - But I like to be explicit 
  */
  sourceKey: 'id',
  foreignKey: 'authorId',
  as: 'books'
});

// models/book.ts
import Author from './author';

// ... Code Defining the Book Model

Book.belongsTo(Author, {
  foreignKey: 'authorId',
  as: 'author'
});

Is that it? I hear you say. Well, if things were that simple in this world I wouldn't be writing this post 😅.

So why wouldn't this work? Sequelize has a weird way to work and if we try to define this association in their respective files (as we do in JS) Sequelize will throw this error:

throw new Error("${source.name}.${_.lowerFirst(Type.name)} called with something that's not a subclass of Sequelize.Model");
      ^
"Error: Book.belongsTo called with something that's not a subclass of Sequelize.Model"

At first, I thought I was missing something or that I didn't type the Author Model as a Sequelize Model but after double-checking everything was good, TypeScript was not complaining that I was trying to call the belongsTo method with something else that's not a Sequelize Model. So I was wondering why is this happening? 🤔

I was reading the Sequelize documentation and posts from around the web and didn't find anything that would work, except someone (sorry didn't find the link to the StackOverflow thread) that suggested that one should put their association in one Model file. I was skeptical about it since I said to myself: how would this work since I'm exporting the same model that is in my file. However, I gave it a try. I moved the belongsTo call to the models/author.ts file:

// model/author.ts
import Book from './book';

// ... a bunch of code here

Book.belongsTo(Author, {
  foreignKey: 'authorId',
  as: 'author'
});

And Lord and behold my project was running:

The library Server is running on http://localhost:3000

It is weird but it seems that you have to define the belongsTo association in the same file that you set the hasMany or the hasOne association.

Conclusion

In the end, setting up Sequelize with TypeScript wasn't hard at all, and now we know which properties belong to which model.

For me, it was a valuable experience since I thought that translating my JS files to TS would just be done by renaming the file and that would be it since I believed that Sequelize would handle the typing work in the background.

Note: I know that there is a package out there called sequelize-typescript but I didn't feel like adding another dependency to my project, plus this package is not maintained by the Sequelize team. However, I just tried it and it's pretty cool, so give it a try if you don't want a setup like mine.

By the end of the day, I don't feel like having another dependency in my project, and I was able to accomplish the goal of adding TypeScript to Sequlize without a third-party library just with pure TS.

Sorry for the long post, but I hope you find it useful if you are trying to use Sequelize and TypeScript together.👋🏾

The Power of Automation with GitHub Action - How to Create your Action

Jean Carlos Taveras — Fri, 29 May 2020 01:57:55 +0000

In the past two to four months I started to manage a new project where thankfully I was able to apply a lot of the things that I've been learning from courses and readings while having in mind the experience of the team members that I'm working with to make things easy but at the same time a little bit challenging so I can encourage them to learn new things or reinforced the knowledge that they currently have.

In the first two weeks of the project, we had to deliver an MVP so we decide to host it in Heroku where I created a pipeline for multi-environment, which now that I think about it was an overkilled 😅 since it was just an MVP.

Moving on, I wanted to be able to push my Docker images to the Heroku Registry so every little piece of code that was merged I manually built the image and pushed it to Heroku.

So far so good, but I was getting tired of doing the same thing over and over again, so that's when I remember that I can use GitHub Actions to automate this process 💡. I search the GitHub Marketplace for something that allows me to build and push my docker images to Heroku, I found some things, but it wasn't what I wanted. So I did whatever an engineer would do, create its action 😎.

Read the Docs!

Since I've never worked with Action I have to go and read the documentation which I found out that it is a well-documented feature.

Something that caught my attention was that one can write their actions for some of the common programming languages such as JavaScript, Python, and Java. You can read more about the supported languages and framework here.

Now that I know that I can write an action for my project, I then went ahead and landed on the create actions page, here I noticed that you can write your Actions with JavaScript or Bash, which is cool 😉 for me.

Building the action

I decided to use JavaScript to write my action so as usual, create a folder for your project:

mkdir my-action && cd my-action

Add the `action.yml`

Open your project directory with your favorite IDE or Code Editor and create a new file called action.yml. This file is where you are going to define your action metadata and should have the following structure:

name: # Name of your action
description: # Some Fancy description explaining what this does
inputs: # User input for you action
  id_of_your_input:
    description: # What is this input about
    required: # Set this to true if the input is required or set it to fall if otherwise
    default: # Some default value
outputs:
  time: # id of output
    description: 'The time we greeted you'
runs:
  using: 'node12'
  main: 'index.js'

So I created my action.yml and it looks something like this:

name: 'Deploy Docker Image to Heroku App'
author: 'Jean Carlos Taveras'
description: 'A simple action to build, push and Deploy a Docker Image to your Heroku app.'
inputs:
  email:
    description: 'Email Linked to your Heroku Account'
    required: true
  api_key:
    description: 'Your Heroku API Key'
    required: true
  app_name:
    description: 'Your Heroku App Name'
    required: true
  dockerfile_path:
    description: 'Dokerfile path'
    required: true
  options:
    description: 'Optional build parameters'
    required: false
runs:
  using: 'node12'
  main: 'dist/index.js'

Install Dependencies

Before you can start coding you need to install two dependencies

@actions/core
@actions/github

The @actions/core is required for you to be able to pull the declared input and output variables and more from the action.yml. On the other hand, the @actions/github is used to get information about the Action Context and more.

npm install -s @actions/core @actions/github

Write the core of the action

Create an index.js file and let's import the dependencies:

const core = require('@actions/core');
const github = require('@actions/github'); // In case you need it

Since I'm going to need to execute docker and Heroku commands I'll need to add the child_process and the util modules and get the promisify function from the latter one.

...
const { promisify } = require('util');

const exec = promisify(require('child_process').exec);

Nice! Now I have to create a function to allow authentication to the Heroku Registry.

...

async function loginHeroku() {
  const login = core.getInput('email');
  const password = core.getInput('api_key');

  try { 
    await exec(`echo ${password} | docker login --username=${login} registry.heroku.com --password-stdin`); 
    console.log('Logged in succefully ✅');    
  } catch (error) { 
    core.setFailed(`Authentication process faild. Error: ${error.message}`);    
  } 
}

Good! Now I need to build the Docker image, push it to the Heroku Registry and deploy it to the Heroku App

...

async function buildPushAndDeploy() {
  const appName = core.getInput('app_name');
  const dockerFilePath = core.getInput('dockerfile_path');
  const buildOptions = core.getInput('options') || '';
  const herokuAction = herokuActionSetUp(appName);

  try {
    await exec(`cd ${dockerFilePath}`);

    await exec(`docker build . --file Dockerfile ${buildOptions} --tag registry.heroku.com/${appName}/web`);
    console.log('Image built 🛠');

    await exec(herokuAction('push'));
    console.log('Container pushed to Heroku Container Registry ⏫');

    await exec(herokuAction('release'));
    console.log('App Deployed successfully 🚀');
  } catch (error) {
    core.setFailed(`Something went wrong building your image. Error: ${error.message}`);
  } 
}

Now that I see this, I need to refactor this function 😅. I think I took it too seriously when I said let's Write the core of our action.

As you might notice there's a function called herokuActionSetUp which is just a helper function that returns the Heroku action (push or release).

...

/**
 * 
 * @param {string} appName - Heroku App Name
 * @returns {function}
 */
function herokuActionSetUp(appName) {
  /**
   * @typedef {'push' | 'release'} Actions
   * @param {Actions} action - Action to be performed
   * @returns {string}
   */
  return function herokuAction(action) {
    const HEROKU_API_KEY = core.getInput('api_key');
    const exportKey = `HEROKU_API_KEY=${HEROKU_API_KEY}`;

    return `${exportKey} heroku container:${action} web --app ${appName}` 
  }
}

We are almost done. We just need to call our functions and since these functions are asynchronous then we can chain them together as follow:

...

loginHeroku()
  .then(() => buildPushAndDeploy())
  .catch((error) => {
    console.log({ message: error.message });
    core.setFailed(error.message);
  })

Bundle your code

To prevent committing your node_modules/ folder you can run:

npx zeit/ncc build index.js

This will create a dist folder with a bundle index.js file bare in mind that you have to change the runs section in your action.yml file to point to the bundled JavaScript file:

runs:
  using: 'node12'
  main: 'dist/index.js'

Add a README

You should add a README.md file to let users to how to use your action.

Testing your Action

You can follow the instructions in the GitHub documentation Testing out your action in a workflow. However, I found this method of testing really painful since you have to push your code every time you make a change. What you can do then is run your actions locally by using nektos/act is a well-documented tool and easy to use.

That's it, that's all you need to know to create an action with JavaScript. This post turned out to be a little bit longer than I thought it would since this is my first post.

Thanks and check this action in the GitHub Marketplace Deploy Docker Image to Heroku App as well as the repo at jctaveras/heroku-deploy.