@workestral/odm

ODM do Workestral para Firestore. Encapsula os modelos de domínio e expõe repositórios type-safe. Construído sobre @vorisc/firestore-odm.

Setup

import { createWorkestralOdmClient } from '@workestral/odm'

export const db = createWorkestralOdmClient({
  serviceAccount: process.env.FIREBASE_SERVICE_ACCOUNT!,
  database: '(default)', // opcional
  emulator: false,       // ou true / { host, port }
})

O cliente retornado expõe os repositórios diretamente:

db.user
db.organization
db.organizationMember
db.verificationCode
db.subscription
db.invoice

Repositórios

Cada repositório suporta os métodos do BaseRepository do @vorisc/firestore-odm:

| Método | Descrição | |---|---| | findUnique({ where }) | Busca um documento ou retorna null | | findUniqueOrThrow({ where }) | Busca um documento ou lança NotFoundError | | findFirst({ where, orderBy }) | Primeiro resultado ou null | | findMany({ where, orderBy, take, skip, cursor }) | Lista com filtros e paginação | | create({ data }) | Cria um documento | | createMany({ data }) | Cria vários em lote | | update({ where, data }) | Atualiza um documento | | updateMany({ where, data }) | Atualiza vários em lote | | upsert({ where, create, update }) | Cria ou atualiza | | delete({ where }) | Remove por id | | deleteMany({ where? }) | Remove vários (ou todos) | | count({ where? }) | Conta documentos | | aggregate({ where?, _count, _sum, _avg }) | Agregações nativas |

Exemplos

// busca por id
const user = await db.user.findUnique({ where: { id: 'abc' } })

// busca com filtro
const admins = await db.user.findMany({
  where: { 
    role: UserRole.ADMIN, 
    status: UserStatus.ACTIVE 
  },
  orderBy: { createdAt: 'desc' },
  take: 20,
})

// criar
const org = await db.organization.create({
  data: { 
    name: 'Acme', 
    type: OrganizationType.DEVELOPMENT, 
    ownerId: user.id 
  },
})

// atualizar
await db.organization.update({
  where: { 
    id: org.id 
  },
  data: { 
    status: OrganizationStatus.SUSPENDED 
  },
})

// upsert
await db.subscription.upsert({
  where: { 
    id: 'sub_123' 
  },
  create: { 
    planId: 1, 
    priceInCents: 14900, 
    nextInvoiceDate: '2026-06-01', 
    organizationId: org.id 
  },
  update: { 
    status: SubscriptionStatus.ACTIVE 
  },
})

Transações

await db.$transaction(async (tx) => {
  const user = await tx.user.findUniqueOrThrow({ 
    where: { id } 
  })
  tx.user.update({ 
    where: { id }, 
    data: { status: UserStatus.INACTIVE } 
  })
  tx.organization.update({ 
    where: { id: user.organizationId }, data: { ... } 
  })
})

Batch writes

Para writes atômicos sem reads:

await db.$batch((ctx) => {
  ctx.invoice.create({ data: { ... } })
  ctx.subscription.update({ where: { id }, data: { ... } })
})

Variáveis de ambiente

| Variável | Descrição | |---|---| | FIREBASE_SERVICE_ACCOUNT | JSON do service account (string) |

Para rodar com o emulador local:

createWorkestoreClient({
  serviceAccount: '{}',
  emulator: { host: 'localhost', port: 8080 },
})