Type Fields — Identificadores

Type Fields de identificacao encapsulam UUIDs, tokens de autenticacao e assinaturas digitais com validacao rigorosa de formato.

Resumo

Classe	Tipo	Comprimento	Validacao extra	Arquivo
FId	UUID (qualquer versao)	36	Regex UUID	id.format_vo.ts
FIdReq	String livre	1–36	—	id-req.format_vo.ts
FTraceId	UUID v7	36	Regex UUID v7 (RFC 9562)	trace-id.format_vo.ts
FApiKey	UUID v4	36	uuid.validate() + versao 4	api-key.format_vo.ts
FBearer	Token JWT	100–5000	Prefixo "Bearer "	bearer.format_vo.ts
FSignature	Base64	64–512	Regex base64	signature.format_vo.ts

---

FId

Identificador unico universal (UUID). Utilizado como chave primaria de entidades e agregados. Gera UUIDs v7 (ordenados temporalmente) via metodo generate().

import { FId } from "tyforge";

// Criar a partir de string UUID existente
const result = FId.create("0193a5e7-8b3c-7d4e-9f1a-2b3c4d5e6f7a");
// Result<FId, ExceptionValidation>

// Gerar novo UUID v7
const novoId = FId.generate();
novoId.getValue(); // "0193a5e7-8b3c-7d4e-9f1a-2b3c4d5e6f7a"

// Gerar apenas a string UUID (sem wrapper)
const uuidStr = FId.generateId();
// "0193a5e7-..."

Metodos estaticos:

• create(raw, fieldPath?) — valida e cria instancia
• createOrThrow(raw, fieldPath?) — lanca excecao se invalido
• generate() — gera nova instancia com UUID v7
• generateId() — retorna string UUID v7 sem wrapper

---

FIdReq

Identificador de requisicao. Aceita qualquer string de 1 a 36 caracteres, sem restricao de formato UUID. Utilizado para rastrear requisicoes externas e garantir idempotencia.

import { FIdReq } from "tyforge";

const result = FIdReq.create("req-abc-123");
// Result<FIdReq, ExceptionValidation>

const id = FIdReq.createOrThrow("meu-id-externo");
id.getValue();  // "meu-id-externo"
id.formatted(); // "meu-id-externo" (com trim)

---

FTraceId

Identificador de rastreamento distribuido no formato UUID v7 (RFC 9562). Contém timestamp embutido para ordenacao temporal. Ideal para correlacionar logs e metricas entre microservicos.

import { FTraceId } from "tyforge";

// Gerar novo trace ID (no API Gateway)
const traceId = FTraceId.generate();
traceId.getValue(); // "0193a5e7-8b3c-7d4e-9f1a-2b3c4d5e6f7a"

// Validar trace ID recebido (no microservico)
const result = FTraceId.create(headers["x-trace-id"]);

// Extrair timestamp do trace ID
const timestamp = traceId.getTimestamp();
// Date object com o momento da geracao

// Verificar validade sem criar instancia
const valido = FTraceId.isValid("0193a5e7-8b3c-7d4e-9f1a-2b3c4d5e6f7a");
// true

Metodos estaticos:

• generate() — gera nova instancia com UUID v7
• generateString() — retorna string UUID v7 sem wrapper
• isValid(value) — verifica se e UUID v7 valido
• getPattern() — retorna regex para validacao externa

Metodos de instancia:

• getTimestamp() — extrai o Date embutido no UUID v7
• parse() — retorna { timestamp, version, variant } do UUID

Diferenca entre FId e FTraceId:

• FId — identificador de entidade/agregado (aceita qualquer versao UUID)
• FTraceId — identificador de requisicao (obrigatoriamente UUID v7 para ordenacao temporal)

---

FApiKey

Chave de API no formato UUID v4 para autenticacao de aplicacoes cliente.

import { FApiKey } from "tyforge";

// Gerar nova API key
const apiKey = FApiKey.generate();
apiKey.getValue(); // "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"

// Exibir de forma segura (mascarado)
apiKey.toSafeDisplay();
// "a1b2c3d4-****-****-****-0e1f2a3b4c5d"

// Verificar validade
FApiKey.isValid("a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"); // true

Metodos estaticos:

• generate() — gera nova instancia com UUID v4
• generateString() — retorna string UUID v4 sem wrapper
• isValid(value) — verifica se e UUID v4 valido

Metodos de instancia:

• toSafeDisplay() — retorna a chave mascarada, exibindo apenas o primeiro e ultimo segmento

---

FBearer

Token de acesso Bearer para autenticacao em APIs. Deve comecar com o prefixo "Bearer " e ter entre 100 e 5000 caracteres.

import { FBearer } from "tyforge";

const token = "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
const result = FBearer.create(token);
// Result<FBearer, ExceptionValidation>

const bearer = FBearer.createOrThrow(token);
bearer.formatted(); // Garante prefixo "Bearer "

Regras de validacao:

• Comprimento entre 100 e 5000 caracteres
• Deve comecar com "Bearer " (com espaco)
• Conteudo apos o prefixo deve ser nao-vazio

---

FSignature

Assinatura digital no formato base64. Utilizada para verificacao de autenticidade e integridade de dados.

import { FSignature } from "tyforge";

const sig = "dGVzdGUgZGUgYXNzaW5hdHVyYSBkaWdpdGFsIGJhc2U2NC4uLg==...";
const result = FSignature.create(sig);
// Result<FSignature, ExceptionValidation>

const assinatura = FSignature.createOrThrow(sig);
assinatura.formatted(); // Valor com trim

Regras de validacao:

• Comprimento entre 64 e 512 caracteres
• Deve ser uma string base64 valida (/^[A-Za-z0-9+/]+=*$/)
• Conteudo limpo (sem espacos) deve ter no minimo 64 caracteres