Quando você está trabalhando com HarperDB, dá pra usar TypeScript pra melhorar bastante a sua experiência de desenvolvimento. Nesse artigo vou mostrar algumas boas práticas de como usar TypeScript com HarperDB. Vamos falar de estrutura de pastas, boas práticas de código e como configurar melhor o seu projeto pra aproveitar tudo que o HarperDB oferece.

Antes de começar#

Dá uma passada na documentação do HarperDB pra saber como instalar localmente e começar. Você também pode usar o HarperDB Cloud pra começar rapidinho. Mas vou assumir que você já tem sua instância rodando.

Esse repositório está no GitHub da comunidade HarperDB. Você pode clonar e acompanhar junto com o artigo. Vamos usar a versão cloud do banco, mas no repositório você vai encontrar um arquivo docker-compose.yml que pode ser usado pra rodar localmente com docker compose up.

Configurando Node e TypeScript#

Pra usar TypeScript você precisa ter o Node.js instalado, de preferência a última versão LTS. Você confere rodando node -v no terminal. Se ainda não tiver instalado, pode baixar aqui, ou usar um gerenciador de versões como asdf, nvm, ou até o volta.Estou usando a versão 20.7.0 do Node.js, mas você pode usar qualquer versão acima da 18 no momento em que esse artigo foi escrito.

Vamos criar um novo diretório (pode dar o nome que quiser) e, dentro dele, rodar o comando npm init -y. Isso vai gerar um novo arquivo package.json com os valores padrão. Agora vamos instalar o TypeScript como dependência de desenvolvimento rodando npm install --save-dev typescript. Isso instala a última versão do TypeScript no seu projeto.

Vamos também instalar os tipos externos do Node.js rodando npm install --save-dev @types/node. Isso vai permitir usar os tipos do Node.js no nosso projeto.

Por último, vamos adicionar um pacote de suporte chamado tsx, que vai permitir desenvolver a aplicação sem precisar compilar toda vez que mudarmos alguma coisa. Vamos instalar rodando npm install --save-dev tsx.

Agora vamos inicializar o TypeScript com npx tsc --init, isso vai gerar um arquivo tsconfig.json com todas as definições que o TS precisa. Mas vamos precisar mudar alguns valores. Então abre ele, remove tudo e deixa assim:

1
{
2
  "compilerOptions": {
3
    "target": "ESNext",
4
    "module": "NodeNext",
5
    "outDir": "./dist",
6
    "esModuleInterop": true,
7
    "forceConsistentCasingInFileNames": true,
8
    "strict": true,
9
    "skipLibCheck": true
10
  }
11
}

Também vamos usar ESModules, então precisamos mudar a chave type no nosso package.json pra module. Isso vai permitir usar a sintaxe de import no nosso código. Vamos aproveitar e adicionar um script de execução que vai rodar o código compilado. Nosso package.json vai ficar assim:

1
{
2
  "name": "hdb-typescript-best-practices",
3
  "version": "0.0.1",
4
  "description": "",
5
  "main": "index.js",
6
  "type": "module",
7
  "scripts": {
8
    "start": "node --env-file=.env dist/index.js",
9
    "start:dev": "NODE_OPTIONS='--loader=tsx' node --env-file=.env src/index.ts"
10
  },
11
  "keywords": [],
12
  "author": "Lucas Santos <hello@lsantos.dev> (https://lsantos.dev/)",
13
  "license": "GPL-3.0",
14
  "devDependencies": {
15
    "@types/node": "^20.7.1",
16
    "tsx": "^3.13.0",
17
    "typescript": "^5.2.2"
18
  }
19
}

Testando a configuração#

Agora vamos criar uma pasta src e um arquivo index.ts dentro dela. Esse vai ser o ponto de entrada da nossa aplicação. Também vamos adicionar as pastas dist e node_modules no nosso .gitignore (se ainda não tiver feito isso), pra não commitar o código compilado.

O Node.js a partir da versão 20.6 já vem com suporte nativo a arquivos de env, então vamos aproveitar isso pra guardar nossos segredos num arquivo .env, e essa já é a primeira boa prática:

Vamos criar um arquivo .env e adicionar o seguinte conteúdo:

1
EXAMPLE=Ambiente de teste

Agora vamos adicionar o seguinte código no nosso arquivo index.ts:

1
export async function main() {
2
  console.log('Olá mundo!')
3
  console.log(process.env.EXAMPLE)
4
}
5

6
await main()

Agora roda a configuração com npm run start:dev, você deve ver a seguinte saída:

1
$ npm run start:dev
2
Olá mundo!
3
Ambiente de teste

Isso significa que está tudo configurado corretamente!

Configurando os ambientes e o banco de dados#

Agora que sabemos que tudo está funcionando, vamos pro HarperDB Studio criar nosso schema. Vamos criar um novo schema chamado todo e uma tabela chamada todo_items. Essa vai ser a tabela que vai guardar os itens da lista de tarefas.

O hash da tabela vai ser a coluna id:

O Harper tem um schema maleável, então a gente não precisa definir todas as propriedades, só a propriedade de hash inicial, todas as outras vão sendo adicionadas conforme criamos os objetos.

Vamos configurar nossas variáveis de ambiente no arquivo .env:

1
HDB_HOST=https://sua-instancia.harperdbcloud.com
2
HDB_USERNAME=seu usuario
3
HDB_PASSWORD=sua senha
4
HDB_SCHEMA=todo
5
HDB_TABLE=todo_items

Separando as camadas#

Pra nossa aplicação, vamos criar a gloriosa e simples lista de tarefas. Essa aplicação vai ter as seguintes funcionalidades:

• Criar um novo item de tarefa
• Listar todos os itens de tarefa
• Marcar um item de tarefa como concluído
• Apagar um item de tarefa

É uma aplicação simples, mas vai nos permitir explorar algumas das boas práticas de usar TypeScript com HarperDB.

Vamos também usar uma arquitetura em camadas pra separar nosso código. Isso vai permitir uma melhor separação de responsabilidades e deixar nosso código mais fácil de manter. Arquiteturas em camadas fazem o TypeScript brilhar porque a gente pode usar interfaces pra definir nossos contratos e garantir que o código está seguindo a estrutura correta.

Vamos ter pelo menos três camadas:

• Camada de apresentação: é a camada que fala diretamente com o usuário. Pode ser uma CLI, uma aplicação web, ou até uma aplicação mobile. Essa camada é responsável por receber a entrada do usuário e mandar pra próxima camada. No nosso caso, vamos ter a API, que vai ser uma REST API que recebe a entrada do usuário e manda pra próxima camada. Isso permite separar a lógica real da aplicação da camada de apresentação, o que nos deixa livres pra trocar a camada de apresentação por outra tecnologia sem precisar mudar a lógica da aplicação. Então poderíamos adicionar uma CLI, um endpoint GraphQL, gRPC, ou qualquer outra coisa sem precisar mexer na estrutura de baixo.
• Camada de domínio ou serviço: é a camada que vai ter a lógica de negócio da nossa aplicação. Ela é responsável por receber a entrada do usuário já validada e agir sobre ela. Também é responsável por receber os dados da camada de dados e transformá-los no formato correto pra camada de apresentação. Essa camada é a que vai ter mais lógica, e pode ser separada em várias partes. A camada de domínio pode ser acessada por qualquer outra camada, já que é uma parte central do sistema.
• Camada de dados: como o nome já diz, é a camada responsável pelos dados, que podem vir de qualquer fonte, um banco de dados, um cliente externo, etc. Ela é responsável por receber os dados da camada de domínio e transformá-los no formato correto pro banco de dados. Também é responsável por receber os dados do banco e transformá-los no formato correto pra camada de domínio. Essa camada é a que vai ter menos lógica, mas é a mais importante, porque é onde vamos colocar a lógica do banco de dados e a comunicação com ele.

Isso é bem parecido com a famosa arquitetura MVC, mas pega um pouco das definições de Domain Driven Design e de Clean Architecture.

A camada de domínio#

Antes de criar qualquer camada, a gente precisa modelar nosso objeto de domínio, que é o item de tarefa. Isso vai nos dar um entendimento melhor do que precisamos fazer e como fazer. Vai nos ajudar a entender o formato do nosso objeto e como vamos manipulá-lo.

Vamos começar com uma pasta domain dentro de src, onde vamos criar um arquivo chamado TodoItem.ts. Esse vai ser nosso objeto de domínio, então vamos adicionar o seguinte código nele:

1
import { randomUUID } from 'node:crypto'
2

3
export class TodoItem {
4
  constructor(
5
    public title: string,
6
    public dueDate: Date,
7
    readonly id: string = randomUUID(),
8
    public completed: boolean = false,
9
    readonly createdAt: Date = new Date()
10
  ) {}
11
}

Essa é uma classe simples que representa nosso item de tarefa. Ela tem um construtor que recebe o título e a data de vencimento, e define as outras propriedades. O id é um UUID aleatório, o completed é falso por padrão, e o createdAt é a data atual.

Agora podemos criar um novo item de tarefa rodando new TodoItem('Meu primeiro item de tarefa', new Date()). Isso cria um novo item de tarefa com o título Meu primeiro item de tarefa e a data de vencimento como a data atual.

Vamos adicionar algumas funcionalidades no nosso objeto de domínio pra deixá-lo mais útil. Vamos adicionar um método toJSON que retorna o objeto como uma string JSON, e um método estático fromObject que recebe um objeto que bate com o nosso objeto de dados e retorna uma nova instância da classe.

Pra isso vamos precisar criar um schema pra comparar e validar nosso objeto, e esse é o caso de uso perfeito pro Zod! O Zod é uma biblioteca de validação de schema TypeScript-first que permite criar schemas e validar nossos objetos contra eles. Vamos instalá-lo rodando npm install --save zod.

Pra definir o schema temos duas opções:

1. Definir em um arquivo novo e importar no nosso objeto de domínio
2. Definir dentro do próprio objeto de domínio

Eu pessoalmente prefiro a segunda opção, já que tanto o schema quanto o objeto de domínio estão fortemente acoplados e fazem parte do mesmo objeto, então faz sentido deixar tudo no mesmo arquivo. Mas você pode escolher a que fizer mais sentido pra você.

Vamos adicionar o seguinte código no topo do nosso objeto de domínio:

1
import { z } from 'zod'
2

3
const todoItemSchema = z.object({
4
  title: z.string(),
5
  dueDate: z.date(),
6
  id: z.string().uuid(),
7
  completed: z.boolean().default(false),
8
  createdAt: z.date().default(new Date())
9
})
10

11
export type TodoObjectType = z.infer<typeof TodoObjectSchema>

Depois vamos usar esse schema pra garantir que nosso objeto é um item de tarefa válido. Vamos mudar a função fromJSON do nosso objeto de domínio:

1
static fromObject(todoObject: TodoObjectType): InstanceType<typeof TodoItem> {
2
  TodoObjectSchema.parse(todoObject) // Isso lança um erro se o objeto não for válido
3
  return new TodoItem(todoObject.title, todoObject.dueDate, todoObject.id, todoObject.completed, todoObject.createdAt)
4
}

Isso vai analisar a string JSON e retornar uma nova instância da classe. Também podemos adicionar um toObject pra transformar a classe em um objeto serializável, e um método toJSON que retorna a string JSON, o que vai ser útil quando precisarmos mandar o objeto pro banco de dados. Vamos adicionar o seguinte código no nosso objeto de domínio:

1
toObject() {
2
  return JSON.stringify({
3
    title: this.title,
4
    dueDate: this.dueDate,
5
    id: this.id,
6
    completed: this.completed,
7
    createdAt: this.createdAt
8
  })
9
}
10

11
toJSON() {
12
  return JSON.stringify(this.toObject())
13
}

Nosso objeto de domínio final vai ficar assim:

1
import { randomUUID } from 'node:crypto'
2
import { z } from 'zod'
3

4
const TodoObjectSchema = z
5
  .object({
6
    title: z.string(),
7
    dueDate: z.date({ coerce: true }),
8
    id: z.string().uuid().readonly(),
9
    completed: z.boolean().default(false),
10
    createdAt: z.date({ coerce: true }).default(new Date()).readonly()
11
  })
12
  .strip()
13
export type TodoObjectType = z.infer<typeof TodoObjectSchema>
14

15
export class TodoItem {
16
  constructor(
17
    public title: string,
18
    public dueDate: Date,
19
    readonly id: string = randomUUID(),
20
    public completed: boolean = false,
21
    readonly createdAt: Date = new Date()
22
  ) {}
23

24
  toObject() {
25
    return JSON.stringify({
26
      title: this.title,
27
      dueDate: this.dueDate,
28
      id: this.id,
29
      completed: this.completed,
30
      createdAt: this.createdAt
31
    })
32
  }
33

34
  toJSON() {
35
    return JSON.stringify(this.toObject())
36
  }
37

38
  static fromObject(todoObject: TodoObjectType): InstanceType<typeof TodoItem> {
39
    TodoObjectSchema.parse(todoObject)
40
    return new TodoItem(todoObject.title, todoObject.dueDate, todoObject.id, todoObject.completed, todoObject.createdAt)
41
  }
42
}

A camada de dados#

Agora que temos nosso objeto de domínio, podemos começar a criar nossa camada de dados. Essa camada é responsável por se comunicar com o banco de dados e transformar os dados do banco no formato correto pra camada de domínio. Também é responsável por transformar os dados da camada de domínio no formato correto pro banco.

Como estamos usando o Harper, toda nossa comunicação com o banco é feita através de uma API! O que é extremamente útil porque a gente não precisa configurar drivers complicados nem nada do tipo. Então vamos criar um arquivo novo numa pasta data chamado TodoItemClient.ts. Esse vai ser nosso cliente HarperDB.

Nosso cliente é uma API HTTP, então vamos usar o fetch nativo do node pra nos comunicarmos com ele.A fetch api só está disponível a partir do node 18. Vamos adicionar o seguinte código no nosso arquivo TodoItemClient.ts:

1
import { TodoItem, TodoObjectType } from '../domain/TodoItem.js'
2

3
export class TodoItemClient {
4
  #defaultHeaders: Record<string, string> = {
5
    'Content-Type': 'application/json'
6
  }
7
  credentialsBuffer: Buffer
8

9
  constructor(
10
    private readonly url: string,
11
    private readonly schema: string,
12
    private readonly table: string,
13
    credentials: { username: string; password: string }
14
  ) {
15
    this.credentialsBuffer = Buffer.from(`${credentials.username}:${credentials.password}`)
16
    this.#defaultHeaders['Authorization'] = `Basic ${this.credentialsBuffer.toString('base64url')}`
17
  }
18

19
  async upsert(data: TodoItem) {
20
    const payload = {
21
      operation: 'upsert',
22
      schema: this.schema,
23
      table: this.table,
24
      records: [data.toObject()]
25
    }
26

27
    const response = await fetch(this.url, {
28
      method: 'POST',
29
      headers: this.#defaultHeaders,
30
      body: JSON.stringify(payload)
31
    })
32

33
    if (!response.ok) {
34
      throw new Error(response.statusText)
35
    }
36

37
    return data
38
  }
39

40
  async delete(id: string) {
41
    const payload = {
42
      operation: 'delete',
43
      schema: this.schema,
44
      table: this.table,
45
      hash_values: [id]
46
    }
47

48
    const response = await fetch(this.url, {
49
      method: 'POST',
50
      headers: this.#defaultHeaders,
51
      body: JSON.stringify(payload)
52
    })
53

54
    if (!response.ok) {
55
      throw new Error(response.statusText)
56
    }
57
  }
58

59
  async findOne(id: string) {
60
    const payload = {
61
      operation: 'search_by_hash',
62
      schema: this.schema,
63
      table: this.table,
64
      hash_values: [id],
65
      get_attributes: ['*']
66
    }
67

68
    const response = await fetch(this.url, {
69
      method: 'POST',
70
      headers: this.#defaultHeaders,
71
      body: JSON.stringify(payload)
72
    })
73

74
    if (!response.ok) {
75
      throw new Error(response.statusText)
76
    }
77

78
    const data = (await response.json()) as TodoObjectType[]
79
    if (data[0] && Object.keys(data[0]).length > 0) {
80
      return TodoItem.fromObject(data[0])
81
    }
82

83
    return null
84
  }
85

86
  async listByStatus(completed = true) {
87
    const payload = {
88
      operation: 'search_by_value',
89
      schema: this.schema,
90
      table: this.table,
91
      search_attribute: 'completed',
92
      search_value: completed,
93
      get_attributes: ['*']
94
    }
95

96
    const response = await fetch(this.url, {
97
      method: 'POST',
98
      headers: this.#defaultHeaders,
99
      body: JSON.stringify(payload)
100
    })
101

102
    if (!response.ok) {
103
      throw new Error(response.statusText)
104
    }
105

106
    const data = (await response.json()) as TodoObjectType[]
107
    return data.map((todoObject) => TodoItem.fromObject(todoObject))
108
  }
109
}

Como você pode ver, temos todos os métodos que precisamos pra nos comunicar com o banco. Temos o método upsert que cria ou atualiza um registro, o método delete que apaga um registro, o método findOne que busca um registro pelo hash, e o método listByStatus que lista todos os registros que batem com um determinado valor.

A camada de serviço#

A camada de serviço vai ser a cola entre todas as outras camadas. Numa aplicação tão simples quanto essa, ela geralmente não é muito útil, mas é uma boa prática ter ela, assim dá pra adicionar mais lógica depois. Vamos criar uma pasta nova chamada services e um arquivo novo chamado TodoItemService.ts. Essa vai ser nossa camada de serviço.

A camada de serviço vai receber a entrada do usuário já higienizada, executar qualquer lógica de negócio e então mandar pra camada de dados. Também vai receber dados da camada de dados e transformá-los no formato correto pra camada de apresentação.

Vamos adicionar o seguinte código no nosso arquivo TodoItemService.ts:

1
import { TodoItemClient } from '../data/TodoItemClient.js'
2
import { TodoItem, TodoObjectType } from '../domain/TodoItem.js'
3

4
export class TodoItemService {
5
  #client: TodoItemClient
6
  constructor(client: TodoItemClient) {
7
    this.#client = client
8
  }
9

10
  async findOne(id: string) {
11
    return this.#client.findOne(id)
12
  }
13

14
  async findAll() {
15
    return [...(await this.findPending()), ...(await this.findCompleted())]
16
  }
17

18
  async findCompleted() {
19
    return this.#client.listByStatus(true)
20
  }
21

22
  async findPending() {
23
    return this.#client.listByStatus(false)
24
  }
25

26
  async create(todoItem: TodoObjectType) {
27
    const todo = new TodoItem(todoItem.title, todoItem.dueDate)
28
    return this.#client.upsert(todo)
29
  }
30

31
  async update(todoItem: TodoObjectUpdateType) {
32
    const todo = await this.#client.findOne(todoItem.id ?? '')
33

34
    if (!todo) {
35
      throw new Error('Todo not found')
36
    }
37

38
    todo.completed = todoItem.completed ?? todo.completed
39
    todo.dueDate = todoItem.dueDate ?? todo.dueDate
40
    todo.title = todoItem.title ?? todo.title
41

42
    return this.#client.upsert(todo)
43
  }
44

45
  async delete(id: string) {
46
    return this.#client.delete(id)
47
  }
48
}

Repare que, enquanto na implementação do cliente, numa camada mais baixa, temos uma lógica mais genérica que busca por status, no serviço já separamos os comandos em buscar pendentes e concluídos.

Também implementamos um método findAll que chama o método listByStatus duas vezes e depois junta os resultados. Esse é um bom exemplo de como podemos usar a camada de serviço pra adicionar mais lógica na nossa aplicação sem precisar adicionar mais lógica na camada de dados.

Outro aspecto importante de notar é como a camada de serviço já assume que todos os dados vão estar higienizados. Isso é uma boa prática porque permite uma melhor separação de responsabilidades. A camada de apresentação deve ser a responsável por validar os dados na rota, e então mandá-los pra camada de serviço. A camada de serviço deve assumir que os dados já estão validados e higienizados.

A última coisa a notar é que, agora que subimos um nível, a camada de serviço recebe como parâmetro a camada abaixo dela, o que significa que precisamos passar uma instância do cliente da camada de dados pra camada de serviço. Isso se chama inversão de controle e faz parte do Princípio da Inversão de Dependência.

Esse princípio diz que as camadas de nível mais alto não devem depender das camadas de nível mais baixo, mas sim de abstrações. No nosso caso, a camada de serviço depende da camada de dados, mas não depende da implementação da camada de dados, ela depende da abstração da camada de dados, que é o cliente.

Vamos fazer a mesma coisa com a camada de apresentação.

A camada de apresentação#

Agora que temos nossa camada de dados, podemos começar a criar nossa camada de apresentação. Essa camada é responsável por receber a entrada do usuário e mandar pra próxima camada. No nosso caso, vamos ter a API, que vai ser uma REST API que recebe a entrada do usuário e manda pra próxima camada.

Vamos criar uma pasta nova chamada presentation e um arquivo novo chamado restAPI.ts. Essa vai ser nossa interface REST.

Normalmente a gente usa um framework web pra não ter que recriar tudo do zero. Nesse exemplo vamos usar um framework bem rápido chamado Hono, só pra dar um tempo do Express.

Instale ele e o adaptador dele pro Node.js rodando npm install --save hono @hono/node-server.

A implementação da camada de serviço geralmente cai no Factory Pattern, que é um padrão de criação que permite criar objetos sem precisar saber os detalhes de implementação. No nosso caso, vamos usar uma factory pra criar o cliente da Rest API, assim conseguimos receber a camada de serviço via injeção de dependência.

Isso se traduz em algo assim:

1
import { Hono } from 'hono'
2
import { TodoItemService } from '../services/TodoItemService.js'
3

4
export async function restAPIFactory(service: TodoItemService) {
5
  const app = new Hono()
6

7
  app.get('/api/todos/:id', async (c) => {})
8
  app.get('/api/todos', async (c) => {})
9
  app.post('/api/todos', async (c) => {})
10
  app.put('/api/todos/:id', async (c) => {})
11
  app.delete('/api/todos/:id', async (c) => {})
12

13
  return app
14
}

Essa é uma factory bem simples que recebe a camada de serviço e retorna uma nova instância do cliente da Rest API. Vamos implementar as rotas daqui a pouco, mas primeiro vamos voltar pro nosso arquivo index.ts no diretório src. Esse vai ser o ponto de entrada da aplicação.

Lá vamos iniciar as variáveis de ambiente, assim como o cliente do banco e a camada de serviço. Vamos adicionar o seguinte código no nosso arquivo index.ts:

1
import { z } from 'zod'
2
import { TodoItemClient } from './data/TodoItemClient.js'
3
import { TodoItemService } from './services/TodoItemService.js'
4
import { restAPIFactory } from './presentation/api.js'
5
import { serve } from '@hono/node-server'
6
const conf = {
7
  host: process.env.HDB_HOST,
8
  credentials: {
9
    username: process.env.HDB_USERNAME,
10
    password: process.env.HDB_PASSWORD
11
  },
12
  schema: process.env.HDB_SCHEMA,
13
  table: process.env.HDB_TABLE
14
}
15

16
const EnvironmentSchema = z.object({
17
  host: z.string(),
18
  credentials: z.object({
19
    username: z.string(),
20
    password: z.string()
21
  }),
22
  schema: z.string(),
23
  table: z.string()
24
})
25
export type EnvironmentType = z.infer<typeof EnvironmentSchema>
26

27
export default async function main() {
28
  const parsedSchema = EnvironmentSchema.parse(conf)
29
  const DataLayer = new TodoItemClient(
30
    parsedSchema.host,
31
    parsedSchema.schema,
32
    parsedSchema.table,
33
    parsedSchema.credentials
34
  )
35
  const ServiceLayer = new TodoItemService(DataLayer)
36
  const app = await restAPIFactory(ServiceLayer)
37

38
  serve({ port: 3000, fetch: app.fetch }, console.log)
39
}
40

41
await main()

Voltando pro nosso arquivo restAPI.ts, vamos implementar as rotas. A maioria delas só vai ter parâmetros de rota, então vou só colocar aqui e explicar a lógica:

1
import { Hono } from 'hono'
2
import { TodoItemService } from '../services/TodoItemService.js'
3

4
export async function restAPIFactory(service: TodoItemService) {
5
  const app = new Hono()
6

7
  app.get('/api/todos/:id', async (c) => {
8
    try {
9
      const todo = await service.findOne(c.req.param('id'))
10
      if (!todo) {
11
        c.status(404)
12
        return c.json({ error: 'Todo not found' })
13
      }
14
      c.json(todo.toObject())
15
    } catch (err) {
16
      c.status(500)
17
      c.json({ error: err })
18
    }
19
  })
20

21
  app.get('/api/todos', async (c) => {
22
    try {
23
      let data
24

25
      if (c.req.query('completed')) {
26
        data = await service.findCompleted()
27
      } else if (c.req.query('pending')) {
28
        data = await service.findPending()
29
      } else {
30
        data = await service.findAll()
31
      }
32

33
      c.json(data.map((todo) => todo.toObject()))
34
    } catch (err) {
35
      c.status(500)
36
      c.json({ error: err })
37
    }
38
  })
39

40
  app.post('/api/todos', async (c) => {})
41
  app.put('/api/todos/:id', async (c) => {})
42

43
  app.delete('/api/todos/:id', async (c) => {
44
    try {
45
      await service.delete(c.req.param('id'))
46
      c.status(204)
47
      return c.body(null)
48
    } catch (err) {
49
      c.status(500)
50
      c.json({ error: err })
51
    }
52
  })
53

54
  return app
55
}

Pras rotas de post e put, também vamos precisar validar os dados que chegam. O Hono tem um validador pro Zod que podemos usar como middleware, vamos instalar com npm i @hono/zod-validator.

Podemos importar o zValidator dele e adicionar depois do nome da rota, mas antes do handler, assim:

1
app.post('/api/todos', zValidator('json', ourSchema) async (c) => {})

Mas vamos precisar de algumas coisas aqui: primeiro, vamos precisar de um novo tipo pra representar o tipo de criação, e outro pra representar o tipo de atualização. Vamos adicionar o seguinte código no nosso arquivo TodoItem.ts:

1
export const TodoObjectCreationSchema = TodoObjectSchema.omit({ id: true, createdAt: true, completed: true }).extend({
2
  dueDate: z.string().datetime()
3
})
4
export const TodoObjectUpdateSchema = TodoObjectSchema.omit({ createdAt: true }).partial().extend({
5
  dueDate: z.string().datetime().optional()
6
})
7

8
export type TodoObjectType = z.infer<typeof TodoObjectSchema>
9
export type TodoObjectCreationType = z.infer<typeof TodoObjectCreationSchema>
10
export type TodoObjectUpdateType = z.infer<typeof TodoObjectUpdateSchema>

Estamos criando tipos mais restritos a partir de um tipo mais amplo gerado pelo Zod. Precisamos atualizar esse tipo no arquivo de serviço:

1
async create(todoItem: TodoObjectCreationType) {
2
  const todo = new TodoItem(todoItem.title, new Date(todoItem.dueDate))
3
  return this.#client.upsert(todo)
4
}
5

6
async update(todoItem: TodoObjectUpdateType) {
7
  const todo = await this.#client.findOne(todoItem.id ?? '')
8

9
  if (!todo) {
10
    throw new Error('Todo not found')
11
  }
12

13
  todo.completed = todoItem.completed ?? todo.completed
14
  todo.dueDate = new Date(todoItem.dueDate ?? todo.dueDate)
15
  todo.title = todoItem.title ?? todo.title
16

17
  return this.#client.upsert(todo)
18
}

Agora podemos usar esses tipos na camada de apresentação. Vamos adicionar o seguinte código no nosso arquivo restAPI.ts:

1
app.post('/api/todos', zValidator('json', TodoObjectCreationSchema), async (c) => {
2
  try {
3
    const todoItemObject = await c.req.json<TodoObjectCreationType>()
4
    const todo = await service.create(todoItemObject)
5
    c.status(201)
6
    c.json(todo.toObject())
7
  } catch (err) {
8
    c.status(500)
9
    c.json({ error: err })
10
  }
11
})

Agora pra rota de atualização:

1
app.put('/todos/:id', zValidator('json', TodoObjectUpdateSchema), async (c) => {
2
  try {
3
    const todoItemObject = await c.req.json<TodoObjectUpdateType>()
4
    const todo = await service.update({ ...todoItemObject, id: c.req.param('id') })
5
    c.status(200)
6
    return c.json(todo.toObject())
7
  } catch (err) {
8
    c.status(500)
9
    return c.json({ error: err })
10
  }
11
})

E é isso! Temos nossa camada de apresentação pronta!

Testando#

Testar nossa aplicação é só rodar npm run start:dev e fazer requisições pra ela. Pra testar melhor vou deixar um arquivo do Hurl no repositório que você pode usar pra testar a API. Você roda com hurl --test ./collection.hurl. Isso vai rodar todos os testes e garantir que está tudo funcionando como esperado.

Você também pode fazer requisições você mesmo pra API usando curl ou qualquer outra ferramenta que preferir. Depois é só conferir no seu HarperDB Studio se os dados foram inseridos corretamente.

Conclusão#

Nesse artigo aprendemos como configurar um projeto TypeScript com HarperDB, aprendemos a separar nosso código em camadas, e aprendemos a testar nossa aplicação. Também aprendemos algumas boas práticas pelo caminho.

A ideia é que essas camadas não estão gravadas em pedra, você pode adicionar mais camadas se precisar, ou remover algumas se não precisar delas. O importante é ter uma separação clara de responsabilidades e garantir que seu código seja fácil de manter.