Entidades

No Mirror ORM, uma Entidade é uma classe TypeScript que reflete com precisão uma tabela no seu banco de dados. Utilizando-se dos Stage 3 Decorators para mapear sua estrutura de forma estática e ultra-rápida.

A Anatomia de uma Entidade

Uma entidade Mirror é composta por três pilares: a classe, o identificador único e as colunas de dados.

import { Entity, PrimaryColumn, Column } from 'mirror-orm';

@Entity('products')
export class Product {
  @PrimaryColumn({ strategy: 'uuid_v7' })
  id!: string;

  @Column({ name: 'display_name' })
  name!: string;

  @Column({ type: 'number' })
  price!: number;
}

1. O Decorador @Entity

O @Entity vincula sua classe a uma tabela. Se você não passar um nome, o Mirror usará o nome da classe como o nome da tabela no banco (respeitando o case definido).

• Global Filters: Você pode definir filtros que se aplicam a todas as queries desta entidade (ex: multi-tenancy).
• Performance: No momento em que a classe é carregada, o Mirror extrai o “blueprint” da tabela e o armazena no MetadataRegistry.

2. Mapeamento de Colunas (@Column)

O Mirror não tenta adivinhar tipos. Ele exige que você seja explícito quando a conversão de dados é necessária.

• Type Casting Nativo: Através da opção type, o Mirror injeta a lógica de conversão diretamente no JIT Hydrator. Isso significa que converter uma string do banco para um Date ou boolean no JS acontece na velocidade nativa do V8, sem loops de verificação.
• Privacidade de Dados: Use select: false para colunas sensíveis (como password_hash). Elas nunca serão trazidas do banco, a menos que você as peça explicitamente em um find({ select: [...] }).

3. Estratégias de Chave Primária (@PrimaryColumn)

O Mirror suporta as estratégias de ID mais modernas do mercado para evitar colisões e otimizar a indexação:

• identity: Deixa o banco gerar o ID (SERIAL, BIGSERIAL, AUTO_INCREMENT).
• uuid_v7: Gera IDs ordenáveis no tempo diretamente no Mirror (recomendado para performance de insert em tabelas grandes).
• ulid / cuid2: Suporte nativo para identificadores amigáveis a URL e seguros.
• custom: Você define a função de geração.

Ver também: A referência completa de todas as opções de coluna está em Decorators de Coluna. Para mapear relações entre entidades, veja Relacionamentos.