Integração com WebAssembly

Este documento explica como configurar e usar a integração do Swiss Ephemeris em WebAssembly na biblioteca Kaabalah.

Visão geral

O Swiss Ephemeris é uma biblioteca de cálculo astronômico de alta precisão escrita em C, amplamente usada para cálculos astrológicos. Para usá-la em navegadores via nossa biblioteca JavaScript/TypeScript, criamos um wrapper em WebAssembly.

Pré-requisitos

Para compilar o Swiss Ephemeris para WebAssembly, você precisará de:

1. Emscripten SDK (emsdk): A cadeia de ferramentas do compilador para WebAssembly

   • Instruções de instalação: https://emscripten.org/docs/getting_started/downloads.html

2. Código-fonte do Swiss Ephemeris: O código C que será compilado

   • Baixar em: https://www.astro.com/swisseph/swesrc.htm

3. Arquivos de efemérides: Arquivos de dados usados pelo Swiss Ephemeris para cálculos

   • Baixar em: https://www.astro.com/ftp/swisseph/ephe/

Processo de compilação

1. Baixe o código-fonte do Swiss Ephemeris e extraia-o para o wasm/swisseph diretório

2. Instale o Emscripten SDK seguindo as instruções de instalação deles

3. Compile o código usando o script fornecido:

   cd wasm/scripts
   chmod +x compile.sh
   ./compile.sh

4. Verifique os arquivos de saída:

   • wasm/build/swisseph.js: Código glue JavaScript

   • wasm/build/swisseph.wasm: Binário WebAssembly

Integração com a biblioteca

A integração do Swiss Ephemeris em WebAssembly é usada pelo módulo de astrologia para realizar cálculos astronômicos precisos.

Estrutura do módulo

• src/astrology/swisseph.ts: Wrapper que faz interface com o módulo WebAssembly

• src/astrology/index.ts: Funcionalidade principal de astrologia que usa o wrapper

Carregamento dinâmico

O módulo WebAssembly é carregado dinamicamente em tempo de execução, tornando-o compatível tanto com Node.js quanto com ambientes de navegador. Essa abordagem garante que:

1. O código pesado em WebAssembly seja carregado apenas quando necessário

2. O mesmo código funcione tanto no Node.js quanto em navegadores

3. A biblioteca possa degradar graciosamente se o WebAssembly não estiver disponível

Uso no navegador

Para usar o Swiss Ephemeris em um ambiente de navegador:

1. Copie os arquivos WebAssembly para um local acessível pela sua aplicação web:

   • swisseph.js

   • swisseph.wasm

2. Trate questões de origem cruzada: Garanta que seu servidor web esteja configurado para servir arquivos WebAssembly com o tipo MIME correto (application/wasm)

3. Forneça os arquivos de efemérides que o Swiss Ephemeris precisa para os cálculos:

   • Crie um diretório acessível pela sua aplicação web

   • Coloque os arquivos de efemérides (*.se1) nesse diretório

   • Especifique o caminho ao inicializar o módulo Swiss Ephemeris

Uso no Node.js

Para ambientes Node.js:

1. Inclua os arquivos WebAssembly compilados no seu pacote publicado:

   • Adicione-os ao array files em package.json

   • Certifique-se de que eles sejam copiados para o diretório dist durante a build

2. Coloque os arquivos de efemérides em um local conhecido:

   • Por exemplo, em um subdiretório chamado ephe dentro do seu pacote

   • Defina o caminho das efemérides ao inicializar o módulo

Mecanismo de fallback

O módulo de astrologia inclui um mecanismo de fallback para lidar com situações em que o módulo WebAssembly pode não estar disponível:

1. Se a compilação falhar ou os arquivos WebAssembly estiverem ausentes, o módulo se degrada graciosamente

2. Valores substitutos são retornados em vez de lançar erros

3. Um aviso é registrado no console

Exemplo de implementação

import { getBirthChart } from 'kaabalah/astrology';

// Calcular um mapa natal
const chart = await getBirthChart({
  date: new Date('1990-06-15T12:30:00'),
  latitude: 40.7128,
  longitude: -74.0060,
  timezone: -4
});

console.log(`Ascendant: ${chart.ascendant}`);
console.log(`Sun position: ${chart.planets.sun.longitude}`);

Resolução de problemas

Problemas comuns

1. "Módulo WebAssembly não encontrado":

   • Garanta que os arquivos .wasm e .js estejam corretamente incluídos na sua distribuição

   • Verifique os caminhos no seu código

2. "Não é possível encontrar arquivos de efemérides":

   • Verifique se os arquivos de efemérides estão disponíveis no caminho especificado

   • Verifique as permissões dos arquivos

3. "Erro de cálculo":

   • Verifique se os parâmetros de entrada (data, localização) são válidos

   • Garanta que você tenha os arquivos de efemérides corretos para o intervalo de datas

Ferramentas de depuração

• Use as ferramentas de desenvolvedor do navegador para verificar erros relacionados ao WASM no console

• Ative a ASSERTIONS=1 flag durante a compilação para mensagens de erro mais detalhadas

---