DEV Community: Ryan Vieira

Kysely + Kanel: a dupla perfeita

Ryan Vieira — Wed, 25 Dec 2024 23:37:00 +0000

Eu sou uma pessoa que, desde que comecei a elaborar meus primeiros projetos (meu OT Pokémon e meus primeiros websites para o Habbo), sempre optei pelo Raw SQL. Sinceramente, ainda gosto bastante de escrever minhas próprias queries e ter um controle mais preciso sobre essa camada "low-level". Um ORM não me deixa totalmente confortável, pois já perdi dias analisando logs para identificar e otimizar queries ineficientes.

Porém, em muitas codebases onde trabalhei com Raw SQL, a grande maioria não possuía controle de migrations, e o banco de dados tampouco era monitorado. Tudo funcionava na base do improviso: "Precisa de um novo campo? Roda um ALTER TABLE e adiciona uma nova coluna." Essa abordagem era extremamente prejudicial em todos os cenários, diversas questões surgiam, como: "Quais colunas devemos subir no ambiente de produção?", "Quais novas entidades foram criadas?", "Os ambientes estão sincronizados?" — e muitos outros problemas semelhantes.

A solução para meus problemas

Diante de todos esses problemas, decidi adotar novas ferramentas para tornar minha rotina e as das equipes com quem trabalhei mais saudáveis. Eu não queria abrir mão da flexibilidade que tinha, mas também desejava controlar melhor os graus de liberdade da aplicação. Após muita pesquisa, encontrei uma ferramenta que considero a mais completa para resolver esses problemas: o Kysely, ele é um query builder para TypeScript que, além de prático, é completamente type-safe — um ponto super importante para mim. Essa lib chamou tanto minha atenção que comecei a contribuir ativamente na comunidade, tanto diretamente quanto indiretamente, criando plugins para outras bibliotecas open source integradas ao Kysely.

No entanto, uma das maiores dificuldades ao trabalhar com o Kysely é que, diferente de ORM's, ele não possui uma entidade ou uma geração automática de tipos/interfaces. Todo esse trabalho precisa ser feito manualmente, o que pode ser um pouco exaustivo. Durante minhas pesquisas por soluções, encontrei uma ferramenta que acabei adotando em todos os meus projetos envolvendo PostgreSQL: o Kanel. O Kanel gera automaticamente as tipagens do banco de dados, complementando perfeitamente o Kysely.

Além disso, o Kanel possui um recurso adicional para uso direto com o Kysely: o Kanel-Kysely. Tenho contribuído ativamente para esse repositório, ajudando a desenvolver novas features, como filtros de tipos para tabelas de migrations e a conversão de objetos do Zod para camelCase.

Configurando o Kysely

Estarei usando NestJS para ilustrar os exemplos a seguir. Então, se você não entender alguma sintaxe ou algo no código, sugiro dar uma lida na documentação do NestJS. Na minha opinião, ele é o melhor framework JavaScript — ainda mais se você quiser "fugir" do JavaScript. Mas isso é assunto para outro post meu.

De antemão, você precisará ter um repositório com o NestJS inicializado, caso queira seguir os exemplos à risca. Porém, você também pode desenvolver seu próprio código.

De início, vamos precisar instalar o próprio Kysely, sua CLI e o módulo do PostgreSQL para o Node.js.

npm i kysely pg && npm i kysely-ctl --save-dev

Em seguida, vamos precisar criar um arquivo de configuração na raiz do projeto para o Kysely. Também vou utilizar o prefixo do Knex para os nossos arquivos de migrations e seeds.

// kysely.config.ts

import "dotenv/config";

import { defineConfig, getKnexTimestampPrefix } from "kysely-ctl";
import { Pool } from "pg";

export default defineConfig({
  dialect: "pg",
  dialectConfig: {
    pool: new Pool({ connectionString: process.env.DATABASE_URL }),
  },
  migrations: {
    migrationFolder: "src/database/migrations",
    getMigrationPrefix: getKnexTimestampPrefix,
  },
  seeds: {
    seedFolder: "src/database/seeds",
    getSeedPrefix: getKnexTimestampPrefix,
  },
});

Na sequência, vamos rodar o comando npx kysely migrate make create_user_table em nosso terminal. Ele será responsável por criar nossa primeira migration. Em seguida, vamos criar uma nova tabela de usuários e, assim que feito, vamos rodar essa migration no nosso banco de dados com o comando npx kysely migrate latest.

// 20241225222128_create_user_table.ts

import { sql, type Kysely } from 'kysely'


export async function up(db: Kysely<any>): Promise<void> {
  await db.schema
  .createTable("user")
  .addColumn("id", "serial", (col) => col.primaryKey())
  .addColumn("name", "text", (col) => col.notNull())
  .addColumn("email", "text", (col) => col.unique().notNull())
  .addColumn("password", "text", (col) => col.notNull())
  .addColumn("created_at", "timestamp", (col) =>
    col.defaultTo(sql`now()`).notNull(),
  )
  .execute();
}

export async function down(db: Kysely<any>): Promise<void> {
  await db.schema.dropTable("user").execute();
}

Com todos esses passos concluídos, vamos criar um módulo para a nossa base de dados. Repare também que estou usando um plugin do Kysely para converter nossas colunas para camelCase.

// src/database/database.module.ts

import { EnvService } from "@/env/env.service";
import { Global, Logger, Module } from "@nestjs/common";
import { CamelCasePlugin, Kysely, PostgresDialect } from "kysely";
import { Pool } from "pg";

export const DATABASE_CONNECTION = "DATABASE_CONNECTION";

@Global()
@Module({
  providers: [
    {
      provide: DATABASE_CONNECTION,
      useFactory: async (envService: EnvService) => {
        const dialect = new PostgresDialect({
          pool: new Pool({
            connectionString: envService.get("DATABASE_URL"),
          }),
        });

        const nodeEnv = envService.get("NODE_ENV");

        const db = new Kysely({
          dialect,
          plugins: [new CamelCasePlugin()],
          log: nodeEnv === "dev" ? ["query", "error"] : ["error"],
        });

        const logger = new Logger("DatabaseModule");

        logger.log("Successfully connected to database");

        return db;
      },
      inject: [EnvService],
    },
  ],
  exports: [DATABASE_CONNECTION],
})
export class DatabaseModule {}

Configurando o Kanel

Vamos começar instalando nossas dependências.

npm i kanel kanel-kysely --save-dev

Em seguida, vamos criar nosso arquivo de configuração para o Kanel começar a fazer o seu trabalho. Repare que estarei utilizando alguns plugins, como o camelCaseHook (para transformar nossas interfaces em camelCase) e o kyselyTypeFilter (para excluir as tabelas de migrations do Kysely), uma dessas features eu tive o prazer de poder contribuir e facilitar ainda mais o trabalho que tínhamos.

// .kanelrc.js

require("dotenv/config");

const { kyselyCamelCaseHook, makeKyselyHook, kyselyTypeFilter } = require("kanel-kysely");

/** @type {import('kanel').Config} */
module.exports = {
  connection: {
    connectionString: process.env.DATABASE_URL,
  },
  typeFilter: kyselyTypeFilter,
  preDeleteOutputFolder: true,
  outputPath: "./src/database/schema",
  preRenderHooks: [makeKyselyHook(), kyselyCamelCaseHook],
};

Assim que o arquivo for criado, vamos rodar o comando npx kanel em nosso terminal. Repare que foi criado um diretório no caminho especificado no arquivo de configuração. Esse diretório corresponde ao nome do seu schema, no nosso caso, o Public, e dentro dele temos dois novos arquivos: PublicSchema.ts e User.ts. Provavelmente, o seu User.ts estará exatamente assim:

// @generated
// This file is automatically generated by Kanel. Do not modify manually.

import type { ColumnType, Selectable, Insertable, Updateable } from 'kysely';

/** Identifier type for public.user */
export type UserId = number & { __brand: 'UserId' };

/** Represents the table public.user */
export default interface UserTable {
  id: ColumnType<UserId, UserId | undefined, UserId>;

  name: ColumnType<string, string, string>;

  email: ColumnType<string, string, string>;

  password: ColumnType<string, string, string>;

  createdAt: ColumnType<Date, Date | string | undefined, Date | string>;
}

export type User = Selectable<UserTable>;

export type NewUser = Insertable<UserTable>;

export type UserUpdate = Updateable<UserTable>;

No entanto, o mais importante é o arquivo fora desse diretório Public, o arquivo Database.ts, porque é ele quem vamos repassar para o Kysely entender toda a estrutura da nossa base de dados. Dentro do nosso arquivo app.service.ts, vamos injetar o nosso provider do DatabaseModule e repassar para o Kysely o nosso tipo Database.

// src/app.service.ts

import { Inject, Injectable } from "@nestjs/common";
import { Kysely } from "kysely";
import { DATABASE_CONNECTION } from "./database/database.module";
import Database from "./database/schema/Database";

@Injectable()
export class AppService {
  constructor(@Inject(DATABASE_CONNECTION) private readonly db: Kysely<Database>) {}

  async findManyUsers() {
    const users = await this.db.selectFrom("user").select(["id", "name"]).execute();

    return users;
  }
}

Repare que a tipagem que o Kanel gerou está funcionando corretamente, porque nosso editor de código irá sugerir justamente as colunas que criamos em nossa primeira migration.

Considerações finais

Essa é uma dupla que gosto bastante de utilizar em meus projetos pessoais e até mesmo no trabalho (quando tenho a liberdade para isso). Um query builder é a ferramenta essencial para todos que gostam da flexibilidade que o Raw SQL oferece, mas também optam por um caminho "mais seguro". O Kanel também já me poupou muitas horas de debug e criação de novas tipagens. Eu recomendo fortemente que você crie um projeto com esses dois, você com certeza não irá se arrepender.

Link do Repositório: frankenstein-nodejs

C++ Addons no Node.js

Ryan Vieira — Mon, 02 Dec 2024 22:29:00 +0000

O que são C++ Addons?

São uma maneira de aumentar o desempenho e a funcionalidade do seu código em Node.js, estendendo um código C++ diretamente no ambiente de JavaScript. Em outras palavras, um addon em C++ é um módulo que você cria para o Node.js que permite que você escreva funções e bibliotecas em C++ e as use no seu código JavaScript.

São basicamente uma ponte entre o JavaScript e o C++, o que faz com que o Node.js possa executar códigos mais pesados sem perder a flexibilidade e a acima de tudo, sua simplicidade.

Razões para usar C++ Addons no Node.js

Perfomance: C++ é uma linguagem compilada, ele geralmente apresenta uma performance superior quando comparado ao JavaScript, que é uma linguagem interpretada. Além de permitir um uso mais controlado sobre a alocação e desalocação de memória.
Bibliotecas e código legado: Muitos sistemas e bibliotecas legados foram desenvolvidos em C++. Os addons permitem integrar essas bibliotecas de forma eficiente no ambiente, facilitando a reutilização de bases de código já existentes e reduzindo o esforço de reescrita. Além de possuir o acesso a uma gama de bibliotecas que não funcionam diretamente no JavaScript
Nível de sistema: Certos recursos a nível de sistema, que não são acessíveis pelo JavaScript, podem ser utilizados com a ajuda dos addons, permitindo o uso de funcionalidades específicas sempre que necessário.

Como os C++ Addons funcionam?

Compilação: Um addon precisa ser compilado antes de ser usado. Para isso, é necessário ter o node-gyp configurado no seu repositório. Essa ferramenta compila o código C++ para um módulo "nativo" que o Node.js consegue executar.
Bindings: Para a criação de uma "ponte" entre o JavaScript e o C++, você pode usar os pacotes N-API, NAN e/ou diretamente através do V8, libuv, e bibliotecas alternativas do Node.js.
Carregando as funcionalidades: Assim que o código for compilado e uma "ponte" existir entre os dois mundos, as funções criadas podem ser chamadas através do require(), fazendo com que elas sejam acessíveis para o JavaScript

Exemplo Prático

Primeiramente, vamos criar um diretório para nosso código

 mkdir addon
 cd addon

Em seguida, vamos criar inicializar nosso package.json e baixar a lib node-gyp (certifique-se de instalar corretamente as dependências no seu SO)

npm init -y
npm i node-gyp

Dentro do nosso package.json, vamos criar um script de build para nossa addon.

 "scripts": {
    "build": "node-gyp configure build"
  }

Agora, iremos criar nossa addon em C++ e vamos configurar nossa binding.

// array_sum.cpp
#include <node.h>
namespace demo
{

  using v8::Array;
  using v8::Context;
  using v8::Exception;
  using v8::FunctionCallbackInfo;
  using v8::Isolate;
  using v8::Local;
  using v8::Number;
  using v8::Object;
  using v8::Value;

  void SumArray(const FunctionCallbackInfo<Value> &args)
  {
    Isolate *isolate = args.GetIsolate();
    Local<Context> context = isolate->GetCurrentContext();

    Local<Array> array = Local<Array>::Cast(args[0]);
    uint32_t length = array->Length();
    double sum = 0;

    for (uint32_t i = 0; i < length; ++i)
    {
      Local<Value> element = array->Get(context, i).ToLocalChecked();
      if (element->IsNumber())
      {
        sum += element->NumberValue(context).FromJust();
      }
    }

    args.GetReturnValue().Set(Number::New(isolate, sum));
  }

  void Initialize(Local<Object> exports)
  {
    NODE_SET_METHOD(exports, "sum", SumArray);
  }

  NODE_MODULE(NODE_GYP_MODULE_NAME, Initialize)
}

// binding.gyp
{
  "targets": [{
    "target_name": "array_sum",
    "sources": [ "array_sum.cpp" ],
  }]
}

Pronto, assim que criado esses dois arquivos, podemos rodar nosso script de build (npm run build) e aguardar todo o processo para podermos desfrutar da nossa addon. Em seguida, iremos criar um novo arquivo e executar no terminal o comando node index.js

//index.js
const addon = require('./build/Release/array_sum');

const big = [45, 'teste', 5]
const sum = addon.sum(big);
console.log('Resultado:', sum);
// Resultado: 50

Considerações finais

Os addons são recursos poderosos quando o objetivo é otimizar o desempenho em operações críticas ou realizar integração com código nativo. Embora demandem conhecimento em C++ e aumentem a complexidade do projeto, eles podem ser a solução perfeita para situações em que o JavaScript puro não oferece a solução ideal. Graças a ferramentas como a N-API, o desenvolvimento de addons se tornou mais acessível e estável, permitindo que seus projetos combinem a praticidade do JavaScript com a eficiência do C++.

Link do Repositório: cpp-addon-nodejs
Referências: Node.js