Começando com o Jumentix

Responsabilidade no escopo

• Responsável por: rampa pública para juniores adotarem o Jumentix (modelo mental + primeira jornada)
• Camada: conceitos / caminho de aprendizado (não é um pacote de runtime)
• Usado com: guias (REST, realtime, SPA/PWA), hub de pacotes públicos, hubs de apps
• Não responsável por: docs de tooling privado do workspace

O que é

Jumentix é um framework de fábrica de software: você descreve regras de negócio e contratos de API uma vez e gera/executa APIs REST, canais em tempo real e clientes offline a partir do mesmo núcleo. Esta página é a rampa de entrada para desenvolvedores júnior que nunca usaram Jumentix.

Por que existe

Times de produto costumam reconstruir a mesma infraestrutura — wiring HTTP, alinhamento OpenAPI, handlers WebSocket, sync IndexedDB — em todo projeto. Jumentix oferece um caminho repetível para você focar em lógica de domínio em vez de cola de adaptadores. Esta página leva do zero a um primeiro sucesso verificado em menos de 30 minutos.

Pré-requisitos

Instale o Bun se ainda não tiver:

curl -fsSL https://bun.sh/install | bash
bun --version

Leitura prévia (leia uma vez, volte quando um termo aparecer):

• Visão geral
• Arquitetura

Glossário

Passos numerados

Passo 1 — Instalar a toolchain (< 5 minutos)

1. Instale o Bun (veja Pré-requisitos).
2. Confirme o gate de versão: bun --version.

Verificação de sucesso: o comando sai com código 0 e imprime semver ≥ 1.3.13.

Passo 2 — Escolher o caminho inicial (< 2 minutos)

Escolha um caminho — não tente os dois no primeiro dia:

Para times que consomem packages publicados:

bun add @jumentix/cana @jumentix/sdk-rest-client

Para contribuidores no workspace completo:

cd Jumentix
bun install

Verificação de sucesso: bun install termina sem erros; node_modules existe.

Passo 3 — Abrir o backend de referência (< 10 minutos)

Ferramentas privadas de bootstrap não são documentadas neste site público. Para o primeiro backend, estude o app de referência do monorepo:

cd apps/backend-template
bun install
# siga os scripts do package.json / README desse app para subir localmente

Depois abra o guia REST e reproduza o caminho hello nesse template.

Checagem de sucesso: você localiza o adapter HTTP + uma pasta de use-case em apps/backend-template e abre o guia REST em seguida.

Passo 4 — Aprender o modelo mental (< 5 minutos)

Mantenha esta figura visível enquanto lê os guias:

[ Adaptadores ]  Express / Fastify / Socket.IO / gRPC / IndexedDB (Cana)
      ↓
[ Aplicação ] casos de uso, portas
      ↓
[ Domínio ] entidades, regras, eventos

Três regras que evitam a maioria dos erros de júnior:

1. Contratos primeiro — OpenAPI / AsyncAPI / packages compartilhados descrevem a forma antes de ligar handlers.
2. Adaptadores são substituíveis — troque Express por Fastify sem reescrever o domínio.
3. Offline é de primeira classe — @jumentix/cana é o adaptador IndexedDB para PWAs; não é a mesma coisa que localStorage.

Passo 5 — Primeiro sucesso: tocar o Cana no browser (< 10 minutos)

Antes de construir uma API completa, confirme que a toolchain de docs funciona. Execute o playground abaixo — Run deve retornar verde e Reset deve restaurar o estado inicial.

### Primeiros passos

```ts
const client = cana.createClient({
  name: dbName,
  schema: {
  version: 1,
  stores: [
    { name: 'categories', keyPath: 'id', indexes: [{ name: 'byName', keyPath: 'name', unique: true }] },
    {
      name: 'tasks',
      keyPath: 'id',
      indexes: [
        { name: 'byCategory', keyPath: 'categoryId' },
        { name: 'byCompleted', keyPath: 'completed' },
        { name: 'byUpdatedAt', keyPath: 'updatedAt' }
      ]
    }
  ]
}
});
await client.open();
await client.table('categories').add({
  id: 'work',
  name: 'Work',
  color: '#2563eb',
  createdAt: Date.now(),
  updatedAt: Date.now()
});
await client.table('tasks').add({
  id: 'task-1',
  title: 'Write the Cana tutorial',
  categoryId: 'work',
  completed: false,
  priority: 'high',
  createdAt: Date.now(),
  updatedAt: Date.now()
});
return {
  backend: client.backend,
  category: await client.table('categories').get('work'),
  task: await client.table('tasks').get('task-1')
};
```

const client = cana.createClient({
  name: dbName,
  schema: {
  version: 1,
  stores: [
    { name: 'categories', keyPath: 'id', indexes: [{ name: 'byName', keyPath: 'name', unique: true }] },
    {
      name: 'tasks',
      keyPath: 'id',
      indexes: [
        { name: 'byCategory', keyPath: 'categoryId' },
        { name: 'byCompleted', keyPath: 'completed' },
        { name: 'byUpdatedAt', keyPath: 'updatedAt' }
      ]
    }
  ]
}
});
await client.open();
await client.table('categories').add({
  id: 'work',
  name: 'Work',
  color: '#2563eb',
  createdAt: Date.now(),
  updatedAt: Date.now()
});
await client.table('tasks').add({
  id: 'task-1',
  title: 'Write the Cana tutorial',
  categoryId: 'work',
  completed: false,
  priority: 'high',
  createdAt: Date.now(),
  updatedAt: Date.now()
});
return {
  backend: client.backend,
  category: await client.table('categories').get('work'),
  task: await client.table('tasks').get('task-1')
};

Verificação de sucesso: Run do playground completa sem erros; você vê registros IndexedDB criados no painel de saída.

Passo 6 — Fluxos centrais (esta semana)

Complete estes guias na ordem quando precisar de cada capacidade:

Passo 7 — Superfície completa (lookup, não tutoriais)

Exemplos

Chamada mínima de client REST (estático)

Injete o documento OpenAPI no browser — não carregue specs com fs do Node:

const client = api.createMockClient();
const result = await client.request({ method: 'GET', path: '/health' });
console.log(result.status, result.body);

Veja a versão interativa em Criar uma API REST.

Registro offline com Cana (estático)

const client = await cana.open({ name: 'my-app', version: 1 });
await client.put('tasks', { id: '1', title: 'Olá Jumentix' });
const task = await client.get('tasks', '1');
console.log(task.title);

Use o playground Cana no Passo 5 para executar este padrão ao vivo.

Erros comuns

Checklist júnior (“Eu consigo …”)

• Instalar Bun 1.3.13+ e confirmar bun --version.
• Explicar as camadas adaptador → aplicação → domínio usando o diagrama acima.
• Gerar ou abrir um serviço Jumentix e localizar .jumentix/service-profile.json.
• Executar o playground Cana (Run verde, Reset restaura estado).
• Dizer a diferença entre OpenAPI (REST) e AsyncAPI (tempo real).
• Abrir o guia REST e saber que é minha próxima tarefa prática.
• Encontrar docs de pacotes e playgrounds em /docs/pt-BR/jumentix/packages.

Próximo passo

Vá para Criar uma API REST e complete o caminho hello-world de ponta a ponta — essa é a segunda página padrão da jornada de aprendizado.