Configuração Global

O TyForge suporta configuração global via arquivo tyforge.config.json na raiz do projeto. A configuração controla o nível de validação dos schemas e dos TypeFields.

Estrutura do arquivo

{
  "schema": {
    "validate": {
      "create": "full",
      "assign": "type"
    }
  },
  "lint": {
    "root": "src",
    "strict": true,
    "rules": {
      "no-any": "error",
      "no-cast": "error",
      "no-magic-http-status": "warning"
    }
  }
}

Seção schema

schema.validate.create

Nível de validação usado pelo modo create do SchemaBuilder. O modo create é usado para validar dados de entrada novos (ex: input de formulários, APIs).

schema.validate.assign

Nível de validação usado pelo modo assign do SchemaBuilder. O modo assign é usado para hidratar dados já persistidos (ex: registros do banco de dados).

Níveis de validação (TValidationLevel)

Nível	Descrição
"full"	Validação completa: tipo + faixa/comprimento + enum. Padrão para create
"type"	Apenas verificação de tipo (sem validação de faixa, comprimento ou enum). Padrão para assign
"none"	Nenhuma validação. O valor é aceito sem verificação

A separação entre create e assign existe porque:

• create recebe dados de fontes externas não confiáveis (usuário, API) — validação completa é necessária
• assign recebe dados já validados anteriormente e persistidos no banco — verificação de tipo é suficiente para garantir integridade sem custo de validação completa

API de configuração

TyForgeConfig.load(configPath?)

Carrega tyforge.config.json via fs.readFileSync + JSON.parse. Usada pelo CLI do linter (tyforge-lint). Não é chamada pelo framework core (TypeFields, SchemaBuilder, etc).

Retorna Result<IResolvedTyForgeConfig, Exceptions> (Result pattern) — erros de carregamento são representados como err() em vez de exceções.

Resultado é cacheado em singleton — a primeira chamada faz a leitura, chamadas subsequentes retornam o cache.

Cenário	Comportamento
Arquivo encontrado e válido	Carrega, valida, cacheia
Arquivo não encontrado	Retorna defaults silenciosamente
JSON inválido (não é objeto)	Retorna defaults
Path com traversal, null bytes, ou URL remota	Rejeitado por segurança — retorna defaults

Nota: as funções loadTyForgeConfig(configPath?), getTyForgeConfig() e clearConfigCache() continuam disponíveis como exports retrocompatíveis, delegando internamente para os métodos estáticos de TyForgeConfig.

TyForgeConfig.get()

Retorna o config cacheado sincronamente. Retorna null se TyForgeConfig.load() ainda não foi chamado.

TyForgeConfig.clearCache()

Limpa o cache. Útil em testes.

Segurança do carregamento

O path do config é validado antes da leitura:

• Rejeita null bytes (\0)
• Rejeita URLs remotas (https://, ftp://)
• Rejeita path traversal (../)
• Aceita apenas arquivos .json
• Aceita apenas filenames na whitelist: tyforge.config.json, tyforge-lint.config.json
• Resolve symlinks via fs.realpathSync para prevenir symlink traversal

Valores padrão

Se o arquivo tyforge.config.json não existir:

{
  "schema": {
    "validate": {
      "create": "full",
      "assign": "type"
    }
  }
}

TypeField.createLevel e TypeField.assignLevel

A classe base TypeField expõe duas propriedades estáticas públicas com valores padrão hardcoded:

abstract class TypeField<TPrimitive, TFormatted> {
  static createLevel: TValidationLevel = "full";
  static assignLevel: TValidationLevel = "type";
  // ...
}

Essas propriedades são usadas internamente pelos TypeFields concretos ao chamar validateRules() nos métodos create() e assign().

Importante: a classe TypeField não importa tyforgeConfig nem lê o arquivo tyforge.config.json. Os níveis de validação são definidos com valores padrão hardcoded e podem ser alterados programaticamente via TypeField.configure().

Método TypeField.configure()

Permite alterar níveis de validação e locales em tempo de execução:

static configure(options: {
  create?: TValidationLevel;
  assign?: TValidationLevel;
  localeDisplay?: TLocaleDisplay;
  localeRegion?: TLocaleRegion;
  localeData?: TLocaleData;
}): void;

Exemplo de uso no bootstrap da aplicação:

import { TypeField } from "tyforge";

// Desabilita validação no assign para maximizar performance
TypeField.configure({ create: "full", assign: "none" });

// Configura locale brasileiro (exibição + regras de validação + dados)
TypeField.configure({ localeDisplay: "br", localeRegion: "br", localeData: "br" });

• localeDisplay — controla formatação de exibição (formatted(), formatNumber()). Valores: "us" | "br"
• localeRegion — controla regras de validação de negócio. Valores: "us" | "br"
• localeData — controla formatação para API/persistência (formatted("data")). Valores: "us" | "br"

A integração entre o arquivo tyforge.config.json e o TypeField.configure() fica a cargo do projeto consumidor. O CLI do linter (tyforge-lint) lê o arquivo de configuração, mas o framework core não faz isso automaticamente.

Seção lint

A seção lint dentro do tyforge.config.json configura o linter. Alternativamente, o linter pode ser configurado via um arquivo dedicado tyforge-lint.config.json.

A ordem de prioridade para configuração do linter:

1. Flag --config <path> na linha de comando
2. Arquivo tyforge-lint.config.json na raiz do projeto
3. Seção lint dentro de tyforge.config.json
4. Valores padrão

Para detalhes completos sobre a configuração do linter, consulte a documentação do Linter.

Interface ITyForgeConfig

interface ITyForgeConfig {
  schema: {
    validate: {
      create: TValidationLevel;
      assign: TValidationLevel;
    };
  };
  lint?: Record<string, unknown>;
}

Exemplo de uso

Projeto com validação relaxada no assign

{
  "schema": {
    "validate": {
      "create": "full",
      "assign": "none"
    }
  }
}

Neste cenário, dados vindos do banco de dados não passam por nenhuma validação no assign, maximizando a performance em cenários de leitura intensiva.

Projeto em desenvolvimento com validação completa

{
  "schema": {
    "validate": {
      "create": "full",
      "assign": "full"
    }
  }
}

Neste cenário, tanto create quanto assign validam completamente, útil para detectar inconsistências nos dados persistidos durante o desenvolvimento.