<p>O desenvolvimento de <abbr title="Application Programming Interface">API</abbr>s consiste em boa parte do trabalho feito por profissionais de tecnologia (pelo menos daqueles que trabalham com a web) e, ao longo do tempo, surgiram diversos padrões para ajudar a lidar com a complexidade de se desenvolver tais APIs, como <abbr title="Representational State Transfer Application Programming Interface">REST</abbr>, GraphQL e o <abbr title="Remote Procedure Call">RPC</abbr>. Neste artigo, irei tratar do último, usando o <a href="https://trpc.io/">tRPC</a>.</p>
<h2>Mas o que é <abbr title="Remote Procedure Call">RPC</abbr>?</h2>
<p>RPC (<em>Remote Procedure Call</em> - em português: chamada de função remota) é um mecanismo de comunicação entre dois computadores, onde um pode ser identificado como <em>cliente</em> e o outro por ser identificado como <em>servidor</em>. Do ponto de vista do cliente, chamar uma RPC é apenas uma questão de chamar uma função com seus devidos argumentos e aguardar uma resposta, a fim de continuar a execução do programa.</p>
<p><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hzx0azc3l9qcathciv8o.png" alt="Diagrama de uma chamada de função remota (RPC)"></p>
<p>E por que alguém faria isso? Ora, para distribuir seu sistema em servidores distintos, no momento que essa distribuição fizer sentido para o desenvolvimento do sistema.</p>
<h2>Criando uma API com JavaScript e o padrão RPC</h2>
<p>Agora que já sabemos o que é RPC, vamos criar uma API simples que tira proveito deste padrão, usando o <a href="https://fastify.dev/">Fastify</a>). Desse modo poderemos entender melhor o padrão RPC com um exemplo prático e, de quebra, entender como o tRPC funciona.</p>
<p>Vamos criar uma API que irá criar, ler, atualizar e excluir itens em uma lista de tarefa. Vamos começar com o código básico do nosso servidor. Atente-se aos comentários do código abaixo:</p>
<pre><code class="highlited-code-wrapper langjavascript"><div class="highlited-code" data-language="javascript">// server/src/index.js
import Fastify from 'fastify'

// Neste arquivo, definiremos todas as procedures disponíveis
// na nossa API.
import * as procedures from './procedures.js'

const fastify = Fastify()

// Nossa API terá um único endpoint: /rpc e
// só aceita requisições do tipo POST.
fastify.post('/rpc', async (req, res) =&gt; {
  // Toda requisição para /rpc deverá informar
  // qual procedure deseja chamar no corpo da requisição.
  if (!req.body?.procedure) {
    res.status(400).send({
      title: 'Faltam parâmetros obrigatórios',
      details: 'O parâmetro &quot;procedure&quot; é obrigatório.'
    })
  }

  const procedure = procedures[req.body.procedure]
  
  // Se a procedure não estiver definida, retorna um erro
  if (!procedure || typeof procedure !== 'function') {
    return res.status(404).send({
      title: 'Procedure não encontrada',
      details: `A procedure ${req.body.procedure} não foi encontrada.`
    })
  }

  try {
    // Chama a procedure com os argumentos, também
    // passados no corpo da requisição
    const response = procedure?.(req.body.args)

    // Eu espero que toda procedure retorne um objeto
    // com _status_ e _data_.
    return res.status(response?.status || 200).send(response?.data)
  } catch (error) {
    return res.status(error?.code || 500).send({
      title: error?.title || 'Erro',
      details: error?.message || 'Ocorreu um erro.'
    })
  }
})

// Inicia o servidor
try {
  await fastify.listen({ port: 3000 })
} catch (err) {
  fastify.log.error(err)
  process.exit(1)
}
</div>
</code></pre><p>Adicionamos as nossas <em>procedures</em>:</p>
<pre><code class="highlited-code-wrapper langjavascript"><div class="highlited-code" data-language="javascript">// server/src/procedures.js

// Criamos um classe de erro personalizada
// só para as nossas procedures.
class ProcedureError extends Error {
  constructor(message, code, title) {
    super(message)
    this.title = title
    this.code = code
  }
}

// &quot;Banco de dados&quot;
export let tarefas = [
  {
    id: 1,
    title: 'Tarefa 1',
  },
  {
    id: 2,
    title: 'Tarefa 2',
  },
  {
    id: 3,
    title: 'Tarefa 3',
  },
]

// Funções de CRUD

export const getTarefas = () =&gt; {
  return {
    status: 200,
    data: tarefas,
  }
}

export const getTarefa = (id) =&gt; {
  if (!id) {
    throw new ProcedureError('O id é obrigatório', 400, 'Faltam parâmetros obrigatórios')
  }

  const tarefa = tarefas.find((todo) =&gt; todo.id === id)

  if (!tarefa) {
    throw new ProcedureError(`Tarefa ${id} não encontrada`, 404)
  }

  return {
    status: 200,
    data: tarefa,
  }
}

export const addTarefa = (title) =&gt; {
  if (!title) {
    throw new ProcedureError('O título é obrigatório', 400, 'Faltam parâmetros obrigatórios')
  }

  const id = tarefas.length + 1
  const tarefa = {
    id,
    title,
  }

  tarefas.push(tarefa)

  return {
    status: 201,
    data: { id },
  }
}

export const updateTarefa = ({ id, title }) =&gt; {
  if (!id || !title) {
    throw new ProcedureError('O id e o título são obrigatórios', 400, 'Faltam parâmetros obrigatórios')
  }

  const index = tarefas.findIndex((todo) =&gt; todo.id === id)

  if (index === -1) {
    throw new ProcedureError(`Tarefa ${id} não encontrada`, 404)
  }

  tarefas[index].title = title

  return {
    status: 200,
  }
}

export const deleteTarefa = (id) =&gt; {
  if (!id) {
    throw new ProcedureError('O id é obrigatório', 400, 'Faltam parâmetros obrigatórios')
  }

  const index = tarefas.findIndex((todo) =&gt; todo.id === id)

  if (index === -1) {
    throw new ProcedureError(`Tarefa ${id} não encontrada`, 404)
  }

  tarefas = tarefas.filter((todo) =&gt; todo.id !== id)

  return {
    status: 204,
  }
}</div>
</code></pre><p>Vamos iniciar a nossa API com <code>node src/index.js</code> e testar a chamada às nossas procedures. Vou usar o <a href="url"><code>curl</code></a> neste exemplo pois já que estamos usando um emulador de terminal, mas fique a vontade para usar a ferramenta que preferir. Ah, não se esqueça que todas as nossas requisições são do tipo <code>POST</code>:</p>
<pre><code class="highlited-code-wrapper langbash"><div class="highlited-code" data-language="bash">curl --json '{&quot;procedure&quot;: &quot;getTarefas&quot;}' http://localhost:3000/rpc

curl --json '{&quot;procedure&quot;: &quot;getTarefa&quot;, &quot;args&quot;: 1}' http://localhost:3000/rpc

curl --json '{&quot;procedure&quot;: &quot;updateTarefa&quot;, &quot;args&quot;: {&quot;id&quot;: 1, &quot;title&quot;: &quot;Novo título&quot;}}' http://localhost:3000/rpc

curl --json '{&quot;procedure&quot;: &quot;addTarefa&quot;, &quot;args&quot;: &quot;Nova tarefa&quot;}' http://localhost:3000/rpc

curl --json '{&quot;procedure&quot;: &quot;deleteTarefa&quot;, &quot;args&quot;: 4}' http://localhost:3000/rpc</div>
</code></pre><h2>Adicionando TypeScript</h2>
<p>Como queremos uma API cujos tipos possam ser compartilhados do servidor para o cliente, vamos converter o nosso código JavaScript para TypeScript, da seguinte forma (e adicionar algumas melhorias ao mesmo tempo):</p>
<pre><code class="highlited-code-wrapper langtypescript"><div class="highlited-code" data-language="typescript">// server/src/errors.ts

// Vamos separar a nossa classe ProcedureError
// em seu próprio arquivo:

export class ProcedureError extends Error {
  code: number
  title: string | undefined

  constructor(message: string, code: number, title?: string) {
    super(message)
    this.title = title
    this.code = code
  }
}</div>
</code></pre><p>Agora, criamos o arquivo <code>app.ts</code> para colocar o código de configuração do servidor, excluindo a parte que inicia o servidor. Novamente, leia os comentários com atenção:</p>
<pre><code class="highlited-code-wrapper langtypescript"><div class="highlited-code" data-language="typescript">// server/src/app.ts

import Fastify from 'fastify'
import * as procedures from './procedures'
import { ProcedureError } from './errors'

export const app = () =&gt; {
  const fastify = Fastify()
   
  // Adiciona os tipos esperados no Body da requisição.
  fastify.post&lt;{
    Body: {
      procedure: string
      args?: any
    }
  }&gt;('/rpc', async (req, res) =&gt; {
    if (!req.body?.procedure) {
      res.status(400).send({
        title: 'Faltam parâmetros obrigatórios',
        details: 'O parâmetro &quot;procedure&quot; é obrigatório.'
      })
    }
    
    // Fazemos coerção do tipo das procedures.
    const procedure = procedures?.[req.body?.procedure as keyof typeof procedures]

    if (!procedure || typeof procedure !== 'function') {
      return res.status(404).send({
        title: 'Procedure não encontrada',
        details: `A procedure ${req.body.procedure} não foi encontrada.`
      })
    }

    try {
      const response = procedure(req.body.args)
      return res.status(response?.status || 200).send(response?.data)
    } catch (error) {
     // Definimos o tipo de erro esperado.
      const { code, title, message } = error as ProcedureError

      return res.status(code|| 500).send({
        title: title || 'Erro',
        details: message || 'Ocorreu um erro.'
      })
    }
  })

  return fastify
}</div>
</code></pre><p>O arquivo que inicializa o servidor:</p>
<pre><code class="highlited-code-wrapper langtypescript"><div class="highlited-code" data-language="typescript">// server/src/server.ts

import { app } from './app'

const server = app()

try {
  server.listen({ port: 3000 })
} catch (err) {
  server.log.error(err)
  process.exit(1)
}</div>
</code></pre><p>E por fim, adicionaremos os tipos às nossas procedures:</p>
<pre><code class="highlited-code-wrapper langtypescript"><div class="highlited-code" data-language="typescript">// server/src/procedures.ts

import { ProcedureError } from './errors'

// O tipo de estrutura de dados do nosso CRUD.
type Tarefa = {
  id: number
  title: string
}

export let tarefas: Tarefa[] = [
  {
    id: 1,
    title: 'Tarefa 1',
  },
  {
    id: 2,
    title: 'Tarefa 2',
  },
  {
    id: 3,
    title: 'Tarefa 3',
  },
]

// Tipo que define os argumentos e os retornos
// esperados de cada procedure.
// - TData é o tipo genérico que define o retorno dos dados.
// - TArgs é o tipo genérico que define os argumentos que a procedure recebe.
type Procedure&lt;TData = unknown, TArgs = undefined&gt; = (args?: TArgs) =&gt; {
  status: number
  data?: TData
}

export const getTarefas: Procedure&lt;Tarefa[]&gt; = () =&gt; {
  return {
    status: 200,
    data: tarefas,
  }
}

export const getTarefa: Procedure&lt;Tarefa, Tarefa['id']&gt; = (id) =&gt; {
  if (!id) {
    throw new ProcedureError(
      'O id é obrigatório',
      400,
      'Faltam parâmetros obrigatórios'
    )
  }

  const tarefa = tarefas.find((todo) =&gt; todo.id === id)

  if (!tarefa) {
    throw new ProcedureError(`Tarefa ${id} não encontrada`, 404)
  }

  return {
    status: 200,
    data: tarefa,
  }
}

export const addTarefa: Procedure&lt;{ id: Tarefa['id'] }, Tarefa['title']&gt; = (title) =&gt; {
  if (!title) {
    throw new ProcedureError(
      'O título é obrigatório',
      400,
      'Faltam parâmetros obrigatórios'
    )
  }

  const id = tarefas.length + 1
  const tarefa = {
    id,
    title,
  }

  tarefas.push(tarefa)

  return {
    status: 201,
    data: { id },
  }
}

export const updateTarefa: Procedure&lt;undefined, Tarefa&gt; = (args) =&gt; {
  if (!args?.id || !args?.title) {
    throw new ProcedureError(
      'O id e o título são obrigatórios',
      400,
      'Faltam parâmetros obrigatórios'
    )
  }

  const index = tarefas.findIndex((todo) =&gt; todo.id === args.id)

  if (index === -1) {
    throw new ProcedureError(`Tarefa ${args.id} não encontrada`, 404)
  }

  tarefas[index].title = args.title

  return {
    status: 200,
  }
}

export const deleteTarefa: Procedure&lt;undefined, Tarefa['id']&gt; = (id) =&gt; {
  if (!id) {
    throw new ProcedureError(
      'O id é obrigatório',
      400,
      'Faltam parâmetros obrigatórios'
    )
  }

  const index = tarefas.findIndex((todo) =&gt; todo.id === id)

  if (index === -1) {
    throw new ProcedureError(`Tarefa ${id} não encontrada`, 404)
  }

  tarefas = tarefas.filter((todo) =&gt; todo.id !== id)

  return {
    status: 204,
  }
}

// Exportamos os tipos da nossa API
// para serem usados do lado  do cliente.
export type API = {
  getTarefas: typeof getTarefas
  getTarefa: typeof getTarefa
  addTarefa: typeof addTarefa
  updateTarefa: typeof updateTarefa
  deleteTarefa: typeof deleteTarefa
}</div>
</code></pre><p>Com tudo pronto, agora podemos criar o código do nosso cliente e a única coisa que irei usar do código do servidor é o tipo <code>API</code> (que definimos no arquivo <code>src/procedures.ts</code>). Claro, para fazer isso, o código do cliente ou do servidor devem estar no mesmo <a href="https://monorepo.tools/">monorepo</a> ou serem compartilhados via <a href="https://git-scm.com/book/en/v2/Git-Tools-Submodules">git submodules</a>:</p>
<pre><code class="highlited-code-wrapper langtypescript"><div class="highlited-code" data-language="typescript">// client/src/index.ts

// Este é o caminho do código servidor, que pode estar no mesmo 
// monorepo ou pasta, a depender da sua preferência.
import type { API } from '../../server/src/procedures'

// A função query é tudo que você precisará para
// interagir com as procedures do servidor.
const query = &lt;Procedure extends keyof API&gt;(
  procedure: Procedure,
  ...args: Parameters&lt;API[Procedure]&gt;
): Promise&lt;ReturnType&lt;API[Procedure]&gt;&gt; =&gt; {
  return fetch('http://localhost:3000/rpc', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ procedure, args: args[0] }),
  }).then((response) =&gt; response.json()) as any
}</div>
</code></pre><p>E agora, temos uma função que documenta todas as funções disponíveis no nosso servidor (e seus respectivos argumentos) apenas com seus tipos:</p>
<p><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ujxxpvxxqaxxizgo6dvh.png" alt="Mostrando o autocomplete das funções do servidor"></p>
<p>É importante notar que estamos utilizando <code>import type { API } from &#39;../../server/src/procedures&#39;</code> (ênfase no <code>type</code>), pois, depois de compilar o nosso código para JavaScript, não queremos nenhum código do servidor disponível no cliente.</p>
<p>Agora que entendemos o que é RPC e construímos nossa própria API com este padrão, vamos ver como o <a href="https://trpc.io/">tRPC</a> pode nos ajudar.</p>
<h2>Introduzindo o tRPC</h2>
<p>O tRPC pega o conceito de uma API RPC que acabamos de implementar (e que foi inicialmente apresentado pelo Colin McDonell em seu <a href="https://colinhacks.com/essays/painless-typesafety">blog</a>) e adiciona uma experiência de desenvolvimento ainda melhor, com validação dos dados de entrada e saída com <a href="https://github.com/colinhacks/zod">Zod</a> (ou outra biblioteca de validação que você prefira) e até a geração do código do cliente com <a href="https://tanstack.com/query/latest">@tanstack/query</a> e subscrições para envio de dados em tempo real via WebSockets. Dito isto, vamos refazer a API que construímos acima usando <a href="https://trpc.io/">tRPC</a> e Fastify:</p>
<pre><code class="highlited-code-wrapper langtypescript"><div class="highlited-code" data-language="typescript">// server/src/app.ts
import Fastify from 'fastify'
import { fastifyTRPCPlugin } from '@trpc/server/adapters/fastify'
import { appRouter } from './router'

export const app = () =&gt; {
  const fastify = Fastify({ maxParamLength: 5000 })

  fastify.register(fastifyTRPCPlugin, {
    prefix: '/trpc',
    trpcOptions: { router: appRouter},
  });

  return fastify
}</div>
</code></pre><pre><code class="highlited-code-wrapper langtypescript"><div class="highlited-code" data-language="typescript">// server/src/router.ts
import { initTRPC } from '@trpc/server'
import { z } from 'zod'

type Tarefa = {
  id: number
  title: string
}

export let tarefas: Tarefa[] = [
  {
    id: 1,
    title: 'Tarefa 1',
  },
  {
    id: 2,
    title: 'Tarefa 2',
  },
  {
    id: 3,
    title: 'Tarefa 3',
  },
]

export const t = initTRPC.create()
export const appRouter = t.router({
  // Toda operação de busca de dados é uma query
  // ---------------------\/
  getTarefas: t.procedure.query(() =&gt; tarefas),
  // Podemos tipar a entrada (e a saída de dados)
  // usando a excelente biblioteca Zod.
  getTarefa: t.procedure.input(z.number()).query(({ input: id }) =&gt; {
    const tarefa = tarefas.find((todo) =&gt; todo.id === id)

    if (!tarefa) {
      throw new Error('Tarefa não encontrada')
    }

    return tarefa
  }),
  // Toda operação de alteração de dados é uma mutation
  // --------------------------------------\/
  addTarefa: t.procedure.input(z.string()).mutation(({ input: title }) =&gt; {
    const id = tarefas.length + 1

    tarefas.push({ id, title })

    return id
  }),
  updateTarefa: t.procedure
    .input(z.object({ id: z.number(), title: z.string() }))
    .mutation(({ input: { id, title } }) =&gt; {
      const tarefa = tarefas.find((todo) =&gt; todo.id === id)

      if (!tarefa) {
        throw new Error('Tarefa não encontrada')
      }

      tarefa.title = title

      return id
    }),
  deleteTarefa: t.procedure.input(z.number()).mutation(({ input: id }) =&gt; {
    const tarefa = tarefas.find((todo) =&gt; todo.id === id)

    if (!tarefa) {
      throw new Error('Tarefa não encontrada')
    }

    tarefas = tarefas.filter((todo) =&gt; todo.id !== id)

    return id
  }),
})

// Exporta a definição de tipos do router
export type AppRouter = typeof appRouter</div>
</code></pre><pre><code class="highlited-code-wrapper langtypescript"><div class="highlited-code" data-language="typescript">import { app } from './app'

const server = app()

try {
  server.listen({ port: 3000 })
} catch (err) {
  server.log.error(err)
  process.exit(1)
}</div>
</code></pre><p>Se você leu os comentários do arquivo <code>server/src/router.ts</code> verá que o tRPC utiliza o mesmo modelo mental de operações do GraphQL, chamando as operações de busca de dados de <em>query</em> e as operações de alteração de dados de <em>mutation</em> (inclusive, pode-se dizer que o GraphQL é uma implementação de RPC que adiciona uma linguagem de busca e a documentação das entidades que são disponibilizadas pela API).</p>
<p>No cliente, podemos utilizar o serviço básico do tRPC (similar ao que fizemos em nossa função <code>query</code> no exemplo anterior:</p>
<p><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gagmnv6duxkuzbu4lthj.png" alt="Tipagem dos endpoint do cliente do tRPC"></p>
<p>Ou, caso nosso frontend seja feito em React ou Next.js, podemos usar o cliente que se aproveita das facilidades do <a href="https://tanstack.com/query/latest">@tanstack/query</a>.</p>
<p>Se você leu até e quer mexer no código utilizado neste artigo, acesse <a href="https://github.com/DouglasdeMoura/rpc-typesafe-api">este repositório</a> no GitHub. Você também pode ver a <a href="https://www.youtube.com/watch?v=tVMmVDELuLE">minha palestra no NodeBR #61</a> onde faço uma introdução ao tRPC.</p>
<h3>Referências</h3>
<ul>
<li><a href="https://www.youtube.com/watch?v=tVMmVDELuLE">Desenvolvendo APIs fortemente tipadas de ponta a ponta com tRPC - NodeBR #61</a>;</li>
<li><a href="https://colinhacks.com/essays/painless-typesafety">Building an end-to-end typesafe API — without GraphQL</a></li>
</ul>


Douglas Moura

Douglas Moura

#rpc

Desenvolvendo APIs fortemente tipadas de ponta a ponta com tRPC