AstrologyJS
AstrologyJS is a NodeJs package that provides functionality for including astrological charts in projects.
Installation
To use AstrologyJS in a project, run the following in a terminal from the root of your project. This will save AstrologyJS as a dependency within your package.json
file.
npm install astrologyjs --save
Usage
Although there are a number of classes included in the package, the main ones that you'll need are Person
, Chart
, ChartFactory
, and ChartType
. Import them as follows:
// Typescript/ES6 style; // Node.js stylelet Person = Person;let Chart = Chart;let ChartFactory = ChartFactory;
Person
Create a To create a new chart, first you have to create one or more Person objects. Since creating a person may require some asynchronous calls, you need to use either the Promise
style or async/await
:
// Using Promiselet person;Person; // Using async/awaitlet person;try person = await Person; catch err // uh-oh...// ...do other stuff, i.e. create a chart
The parameters for Person.create()
are:
- The name of the person (or event, if this is an event chart):
string
- The (precise as possible) date and time for the chart:
Date
orstring
in ISO 8601 format Be very careful when setting dates to make sure you've properly accounted for the timezone. Using a UTC datetime in the ISO 8601 format is recommended since this format includes accurate timezone information. If you use aDate
object, be aware that it usually defaults to the timezone in which the computer creating it is located. If this is not the same as the timezone for the chart, your data may come back inaccurate. - The location for the chart: an
Object
like{lat: 37.4381927, lng: -79.18932}
or astring
address If you submit astring
addres, e.g. "221B Baker St, Marylebone, London NW1 6XE, UK", behind the scenesAstrologyJS
will use Google's geocoding service to convert that into a latitude and longitude. If you already know the lat/lng, however, passing them will preventPerson.create()
from being asynchronous.
If you are creating a Synastry, Combined, or Davison chart, you'll need to create two Person
objects.
Chart
Create a Chart data is loaded from a remote online ephemeris REST service. As such, when creating a new Chart
you should use ChartFactory
. If building an app that stores charts for later viewing, it is recommended that the instantiated Chart
objects be serialized and stored so that they can be retrieved again later without having to use the factory.
// Using Promiselet chart;ChartFactory; // Using async/awaitlet chart;try chart = await ChartFactory; catch err // uh-oh... (probably means web service was unavailable for some reason)// ... do stuff with your chart ...
Parameters for ChartFactory.create()
are:
- A name for your chart:
string
- A person (or event):
Person
- A second person:
Person
- The chart type: one of
ChartType.{Basic, Transits, Synastry, Combined, Davison, CombinedTransits, DavisonTransits}
Here are some example call signatures. (I've left out the try/catch
for brevity.)
let jack = Person;let jill = Person; let natal = await ChartFactory;let txits = await ChartFactory;let snsty = await ChartFactory;let cmbnd = await ChartFactory;let cmbtx = await ChartFactory;let davsn = await ChartFactory;let davtx = await ChartFactory;
Charts with transits default to the current time with the location set to the location of the first Person
passed into the create()
function. If you'd like to set transit to a specific time, that can be done after the chart has been created by using the Chart.refreshTransits()
function:
// create a chart with transitslet txits = await ChartFactory; // update them to a specific time, e.g. New Year's eve this yearawait txits;
The order of the Person
objects submitted to the chart determines whether they are considered "inner" or "outer", as follows:
- If there's only one "person", i.e. Basic, Combined, Davison, the planets are "outer"
- If there are transits, the transiting planets are "outer" and the "main" planets are "inner"
- For Synastry, the first
Person
is "inner" and the secondPerson
is "outer"
Chart
Using a Once the chart has been instantiated, you can make use of it's data however you like via the Chart
class' accessor properties:
Chart.houses
: returns an array of longitudes corresponding to the house cusps, starting with the 1stChart.aspects
: returns an array ofAspect
objectsChart.ascendant
: returns the longitude of the ascendant; same as the 1st house cuspChart.innerPlanets
/Chart.outerPlanets
: arrays ofPlanet
objects
The interfaces for the Aspect
and Planet
classes are as follows:
interface Aspect type: string; // e.g. trine, square, sextile, etc. orb: number; // number of degrees (decimal) from making a "perfect" aspect symbol: string; // character corresponding to the symbol for the aspect in the Kairon Semiserif font isMajor: boolean; // "major" aspects: conjunct, sextile, square, trine, opposition; all others are "minor" isApplying: boolean; // is the aspect applying or separating? interface Planet name: string; // name of the planet longitude: number; // position in the sky latitude: number; // degrees above or below the ecliptic speed: number; // mainly used to determine if the planet is retrograde symbol: string; // character corresponding to the symbol for the planet in the Kairon Semiserif font isMajor: boolean; // "major" planets: Sun, Moon, Mercury-Pluto; all others considered "minor" isRetrograde: boolean; // this.speed < 0
What Else?
There are probably lots of other things you can do with the code. I've endeavored to make the source code fairly well documented. Please feel free to ask questions via the issues page as well as alerting me to bugs or other problems.
License
AstrologyJS is open-sourced software licensed under the MIT license.