delprops

Especificação e biblioteca de análise do formato de arquivo .delprops — arquivo de propriedades/configuração do ecossistema Delégua.

Estrutura do projeto

Cada namespace de propriedades é representado como um arquivo .ts dentro de uma pasta com o nome do namespace raiz:

fontes/
├── tipos.ts              ← tipos compartilhados (TipoValor, DefinicaoPropriedade)
├── liquido/
│   ├── roteador.ts       ← propriedades de liquido.roteador.*
│   ├── dados.ts          ← propriedades de liquido.dados.<nome>.*
│   ├── autenticacao.ts   ← propriedades de liquido.autenticacao.*
│   └── index.ts
└── index.ts

Cada arquivo exporta um array de DefinicaoPropriedade:

import { DefinicaoPropriedade } from '../tipos';

const roteador: DefinicaoPropriedade[] = [
    { nome: 'cors', tipo: 'logico', detalhe: 'Habilita CORS.' },
    // ...
];

export default roteador;

O tipo DefinicaoPropriedade é:

export type TipoValor = 'logico' | 'texto' | 'numero';

export interface DefinicaoPropriedade {
    nome: string;
    tipo: TipoValor;
    detalhe: string;
    valoresPermitidos?: string[]; // apenas para propriedades enumeradas
}

A raiz da biblioteca exporta tudo de forma agrupada por namespace:

import { liquido } from '@designliquido/delprops';

// liquido.roteador → DefinicaoPropriedade[]
// liquido.dados    → DefinicaoPropriedade[] (fallback genérico)
// liquido.autenticacao → DefinicaoPropriedade[]

Esquemas contribuídos por pacotes externos

Pacotes do ecossistema Delégua podem contribuir com seus próprios esquemas de propriedades para um namespace. O mecanismo tem duas partes:

1. Declaração no package.json do pacote contribuidor

Adicione uma chave "delprops" ao package.json do pacote:

"delprops": {
    "espacoNomes": "liquido.dados",
    "esquema": "./delprops/dados"
}

• espacoNomes: o caminho do espaço de nomes que este pacote estende.
• esquema: caminho relativo à raiz do pacote para o arquivo de esquema (sem extensão .js/.ts).

2. O arquivo de esquema

Crie o arquivo apontado por esquema. Ele deve exportar default um array de DefinicaoPropriedade:

// meu-pacote/delprops/dados.ts
import { DefinicaoPropriedade } from '@designliquido/delprops';

const dados: DefinicaoPropriedade[] = [
    {
        nome: 'tecnologia',
        tipo: 'texto',
        detalhe: 'Tecnologia de banco de dados.',
        valoresPermitidos: ['minha-tecnologia'],
    },
    // ...
];

export default dados;

Descoberta automática

Use descobrir() para escanear um diretório node_modules e registrar automaticamente todos os pacotes que declaram "delprops":

import path from 'path';
import { descobrir } from '@designliquido/delprops';

descobrir(path.join(__dirname, 'node_modules'));

Registro manual

Use registrar() quando preferir controle explícito sobre o que é carregado:

import { registrar } from '@designliquido/delprops';
import dadosSqlite from '@designliquido/lincones-sqlite/delprops/dados';

registrar('liquido.dados', '@designliquido/lincones-sqlite', dadosSqlite);

Consulta

import { obter, temRegistro } from '@designliquido/delprops';

if (temRegistro('liquido.dados')) {
    const propriedades = obter('liquido.dados');
    // → DefinicaoPropriedade[] de todos os pacotes registrados para este namespace
}

Pacotes que implementam este contrato

| Pacote | Namespace(s) | Contribuição | |--------|--------------|--------------| | liquido | liquido.roteador, liquido.autenticacao | Schemas autoritativos do framework | | @designliquido/lincones-sqlite | liquido.dados | SQLite | | @designliquido/lincones-postgresql | liquido.dados | PostgreSQL | | @designliquido/lincones-mysql | liquido.dados | MySQL |

O formato .delprops

O .delprops é o formato padrão de configuração para projetos Delégua, inspirado no formato .properties do Java. Cada linha não vazia e não comentada define uma propriedade no formato:

<namespace>.<subnamespace>[.<subnamespace>...] = <valor>

Comentários

Comentários de linha são iniciados com //:

// Isto é um comentário
liquido.roteador.cors = verdadeiro

Tipos de valor

| Tipo | Exemplos | |---------|-----------------------------------| | Lógico | verdadeiro, falso | | Texto | 'publico', 'sqlite', ':memory:' | | Número | 3000, 5432 |

Namespace liquido

O namespace liquido é reservado para a configuração do framework web Líquido.

liquido.roteador

Controla o comportamento do roteador HTTP.

| Propriedade | Tipo | Descrição | |---------------------|---------|--------------------------------------------------------| | diretorioEstatico | texto | Caminho do diretório de arquivos estáticos. | | cors | lógico | Habilita CORS. | | bodyParser | lógico | Habilita o body-parser. | | morgan | lógico | Habilita o log de requisições com morgan. | | cookieParser | lógico | Habilita o cookie-parser. | | passport | lógico | Habilita o passport para autenticação. | | json | lógico | Habilita o suporte a JSON no body. | | helmet | lógico | Habilita o helmet para segurança de cabeçalhos HTTP. | | porta | número | Porta em que o servidor escutará. |

Exemplo:

liquido.roteador.diretorioEstatico = 'publico'
liquido.roteador.cors = verdadeiro
liquido.roteador.bodyParser = verdadeiro
liquido.roteador.morgan = verdadeiro
liquido.roteador.cookieParser = verdadeiro
liquido.roteador.passport = falso
liquido.roteador.json = verdadeiro
liquido.roteador.helmet = verdadeiro
liquido.roteador.porta = 3000

liquido.dados.<nome>

Configura uma fonte de dados nomeada. <nome> é um identificador livre escolhido pelo projeto (ex: lincones, principal, cache).

| Propriedade | Tipo | Descrição | |--------------|---------|-------------------------------------------------------------------------------| | tecnologia | texto | Tecnologia de banco de dados. Valores permitidos: sqlite, mysql, postgres, mongodb, mssql. | | caminho | texto | Caminho do arquivo de banco de dados (ex: ':memory:' para SQLite em memória). | | host | texto | Endereço do servidor de banco de dados. | | porta | número | Porta do servidor de banco de dados. | | usuario | texto | Nome de usuário para conexão. | | senha | texto | Senha para conexão. | | banco | texto | Nome do banco de dados. |

Exemplo:

// Banco de dados em memória
liquido.dados.lincones.tecnologia = 'sqlite'
liquido.dados.lincones.caminho = ':memory:'

// Banco de dados PostgreSQL remoto
liquido.dados.principal.tecnologia = 'postgres'
liquido.dados.principal.host = 'localhost'
liquido.dados.principal.porta = 5432
liquido.dados.principal.usuario = 'admin'
liquido.dados.principal.senha = 'segredo'
liquido.dados.principal.banco = 'meu_banco'

liquido.autenticacao

Configura o mecanismo de autenticação da aplicação.

| Propriedade | Tipo | Descrição | |--------------|--------|-----------------------------------------------------------| | tecnologia | texto | Tecnologia de autenticação. Valores permitidos: jwt. |

Exemplo:

liquido.autenticacao.tecnologia = 'jwt'
liquido.autenticacao.segredo = 'minha-chave-secreta'
liquido.autenticacao.expiracao = '7d'

Exemplo completo

// Configuração de arquivos estáticos
liquido.roteador.diretorioEstatico = 'publico'

// Configuração do roteador
liquido.roteador.cors = verdadeiro
liquido.roteador.bodyParser = verdadeiro
liquido.roteador.morgan = verdadeiro
liquido.roteador.cookieParser = verdadeiro
liquido.roteador.passport = falso
liquido.roteador.json = verdadeiro
liquido.roteador.helmet = verdadeiro

// Configuração de bases de dados
liquido.dados.lincones.tecnologia = 'sqlite'
liquido.dados.lincones.caminho = ':memory:'

// Configuração de autenticação
liquido.autenticacao.tecnologia = 'jwt'

Nota: Os schemas autoritativos de liquido.roteador e liquido.autenticacao são definidos pelo próprio pacote liquido em sua pasta delprops/. Os schemas embutidos neste pacote servem como fallback para quando liquido não estiver instalado.

Regras de validação

1. Linhas em branco e comentários (//) são ignorados.
2. Toda linha não vazia deve seguir o formato <chave> = <valor>. Linhas sem = são inválidas.
3. Chave e valor não podem estar vazios.
4. Para propriedades do namespace liquido, o caminho completo deve ser conhecido — propriedades desconhecidas geram aviso.
5. O tipo do valor deve corresponder ao tipo esperado pela propriedade — divergências geram erro.
6. Propriedades com valores enumerados (como tecnologia) só aceitam os valores listados na tabela.
7. Namespaces fora do conjunto conhecido (ex: liquido) são permitidos sem validação de esquema, para uso por outros projetos do ecossistema.