AstroGuile

Biblioteca em TypeScript/JavaScript para cálculo de mapa astral e geração de relatório astrológico com base em celestine.

Uso rápido

const { generateCompleteChartReport } = require('@guilelab/astrological');

const report = generateCompleteChartReport(
  {
    year: 1990,
    month: 7,
    day: 13,
    hour: 11,
    minute: 45,
    timezoneOffset: -3,
    location: {
      latitude: -23.5505,
      longitude: -46.6333
    }
  }
);

console.log(report);

Exemplo pronto

O arquivo exemplo.js imprime o relatório completo em formato legível.

Para executar:

npm run build
node exemplo.js

Cálculo astronômico

Os cálculos são fornecidos por celestine, que não exige configuração de arquivos externos de efemérides.

Entrada esperada

BirthData

| Campo | Tipo | Descrição | |---|---:|---| | year | number | Ano de nascimento. | | month | number | Mês de nascimento, de 1 a 12. | | day | number | Dia do nascimento. | | hour | number | Hora local. | | minute | number | Minuto local. | | timezoneOffset | number | Fuso horário em horas em relação ao UTC. Ex.: -3 para UTC-3. | | location.latitude | number | Latitude do local de nascimento. | | location.longitude | number | Longitude do local de nascimento. |

Saída do relatório

generateCompleteChartReport(...) retorna um objeto AstrologicalReport com três blocos principais:

{
  chart: BirthChart,
  energies: EnergySummary,
  traits: BasicTraitsReport
}

Significado de cada campo

AstrologicalReport

| Campo | Tipo | Significado | |---|---:|---| | chart | BirthChart | Resultado bruto do mapa astral. | | energies | EnergySummary | Resumo dos elementos, qualidades e polaridades. | | traits | BasicTraitsReport | Estrutura JSON com os traços básicos por corpo celeste e uma lista items. |

BirthChart

| Campo | Tipo | Significado | |---|---:|---| | ascendant | number | Grau do Ascendente. | | mc | number | Grau do Meio do Céu (MC). | | planets | Record<string, PlanetPosition> | Posições calculadas dos corpos astrológicos. | | houses | number[] | Cúspides das 12 casas astrológicas. |

PlanetPosition

| Campo | Tipo | Significado | |---|---:|---| | longitude | number | Longitude eclíptica do corpo em graus. | | latitude | number | Latitude eclíptica do corpo. Pode não existir em alguns casos. | | speed | number | Velocidade aparente em longitude. Pode não existir em alguns casos. | | signIndex | number | Índice do signo, de 0 a 11. | | signName | string | Nome do signo em português. |

EnergySummary

EnergySummary contém os totais absolutos e a versão percentual:

| Campo | Tipo | Significado | |---|---:|---| | elementos | Record<ElementType, number> | Soma ponderada dos elementos. | | qualidades | Record<QualityType, number> | Soma ponderada das qualidades. | | polaridade | Record<PolarityType, number> | Soma ponderada da polaridade. | | percent | EnergyTotals | Mesma estrutura acima, mas convertida em percentual. | | aliases | EnergyAliases | Mesma informação dos totais, mas com chaves em inglês. | | percentAliases | EnergyAliases | Mesma informação dos percentuais, mas com chaves em inglês. |

EnergyAliases

| Campo | Tipo | Significado | |---|---:|---| | elements.fire | number | Alias em inglês para elementos.fogo. | | elements.earth | number | Alias em inglês para elementos.terra. | | elements.air | number | Alias em inglês para elementos.ar. | | elements.water | number | Alias em inglês para elementos.água. | | qualities.cardinal | number | Alias em inglês para qualidades.cardinal. | | qualities.fixed | number | Alias em inglês para qualidades.fixa. | | qualities.mutable | number | Alias em inglês para qualidades.mutável. | | polarity.masculine | number | Alias em inglês para polaridade.masculina. | | polarity.feminine | number | Alias em inglês para polaridade.feminina. |

BasicTraitsReport

| Campo | Tipo | Significado | |---|---:|---| | items | TraitInsight[] | Lista ordenada de traços calculados. | | sun | TraitInsight | Traço do Sol. | | moon | TraitInsight | Traço da Lua. | | ascendant | TraitInsight | Traço do Ascendente. | | mercury | TraitInsight | Traço de Mercúrio. | | venus | TraitInsight | Traço de Vênus. | | mars | TraitInsight | Traço de Marte. | | chiron | TraitInsight | Traço de Quíron. | | lilith | TraitInsight | Traço de Lilith. | | northNode | TraitInsight | Traço do Nodo Norte. |

TraitInsight

| Campo | Tipo | Significado | |---|---:|---| | signIndex | number | Índice do signo entre 0 e 11. | | signName | string | Nome do signo correspondente. | | description | string | Frase interpretativa gerada para o corpo. |

ElementType

| Valor | Significado | |---|---| | fogo | Energia de ação, impulso e iniciativa. | | terra | Energia prática, estabilidade e materialização. | | ar | Energia mental, comunicação e troca. | | água | Energia emocional, sensível e intuitiva. |

QualityType

| Valor | Significado | |---|---| | cardinal | Início, movimento e iniciativa. | | fixa | Manutenção, estabilidade e permanência. | | mutável | Adaptação, flexibilidade e transição. |

PolarityType

| Valor | Significado | |---|---| | masculina | Expressão expansiva, ativa e exteriorizada. | | feminina | Expressão receptiva, introspectiva e acolhedora. |

Como as energias são calculadas

A biblioteca soma pesos dos pontos mais relevantes do mapa e converte os totais em percentuais.

Pontos considerados

• Sol
• Lua
• Ascendente
• Meio do Céu (MC)
• Mercúrio
• Vênus
• Marte
• Júpiter
• Saturno
• Urano
• Netuno
• Plutão
• Quíron
• Lilith
• Nodo Norte

Observações

• Quíron, Lilith e Nodo Norte são calculados pelos módulos correspondentes de celestine.
• As frases em traits são descritivas e não substituem uma interpretação astrológica completa.
• Os campos aliases e percentAliases replicam os totais e percentuais com chaves em inglês.

API

generateCompleteChartReport(birthData)

Gera o mapa astral completo e o relatório textual.

Parâmetros

• birthData: dados de nascimento no formato BirthData.

Retorno

Retorna um AstrologicalReport.

AstrologicalEngine

Classe responsável pelo cálculo astronômico do mapa.

ReportGenerator

Classe responsável por transformar o mapa em resumo energético e traços interpretativos.

Estrutura de planetas em chart.planets

As chaves disponíveis no objeto planets são:

• sun
• moon
• mercury
• venus
• mars
• jupiter
• saturn
• uranus
• neptune
• pluto
• chiron
• lilith
• northNode

Observações importantes

• O projeto usa commonjs na saída compilada.
• O arquivo exemplo.js está preparado para demonstrar a leitura do relatório completo no terminal.
• Se você for distribuir a biblioteca, confirme que o diretório de efemérides estará disponível no ambiente consumidor.

Licença

ISC