kaabalah/dist/astrology/index.d.mts

The de-facto library for any esoteric calculations and tooling

/**
 * TypeScript wrapper for Swiss Ephemeris WebAssembly module
 */

declare enum Planet {
    SUN = 0,
    MOON = 1,
    MERCURY = 2,
    VENUS = 3,
    MARS = 4,
    JUPITER = 5,
    SATURN = 6,
    URANUS = 7,
    NEPTUNE = 8,
    PLUTO = 9,
    MEAN_NODE = 10,
    TRUE_NODE = 11,
    LILITH_MEAN = 12,
    LILITH_TRUE = 13,
    CHIRON = 15
}
declare enum VirtualNodes {
    PARS_FORTUNAE = "parsFortunae"
}
declare const PLANET_AND_NODE_NAMES: Record<string, string>;
declare enum HouseSystem {
    PLACIDUS = "P",
    KOCH = "K",
    PORPHYRIUS = "O",
    REGIOMONTANUS = "R",
    CAMPANUS = "C",
    EQUAL = "E",
    WHOLE_SIGN = "W",
    MERIDIAN = "X",
    MORINUS = "M",
    KRUSINSKI = "U",
    ALCABITIUS = "B"
}
declare enum CalcFlag {
    JPL_EPH = 1,
    SWISS_EPH = 2,
    MOSHIER = 4,
    HELIOCENTRIC = 8,
    TRUE_POS = 16,
    J2000 = 32,
    NONUT = 64,
    SPEED3 = 128,
    SPEED = 256,
    EQUATORIAL = 2048,
    TOPOCTR = 32768,
    SIDEREAL = 65536
}
declare enum RiseTransitFlag {
    RISE = 1,
    SET = 2,
    UPPER_MERIDIAN = 4,
    LOWER_MERIDIAN = 8,
    DISC_CENTER = 256,
    NO_REFRACTION = 512
}
interface AzaltResult {
    azimuth: number;
    trueAltitude: number;
    apparentAltitude: number;
}
interface PlanetPosition {
    longitude: number;
    latitude: number;
    distance: number;
    longitudeSpeed?: number;
    latitudeSpeed?: number;
    distanceSpeed?: number;
}
declare const normalizeAngle: (deg: number) => number;

type RuntimeAssetSource = "explicit" | "env" | "candidate" | "bundled";
interface SwissEphRuntimeAssetPaths {
    wasmPath: string;
    ephePath: string;
    wasmPathSource: RuntimeAssetSource;
    ephePathSource: RuntimeAssetSource;
}
interface ResolveSwissEphRuntimeAssetsOptions {
    wasmPath?: string;
    ephePath?: string;
    wasmPathCandidates?: string[];
    ephePathCandidates?: string[];
    env?: Record<string, string | undefined>;
}
declare function resolveSwissEphRuntimeAssets(options?: ResolveSwissEphRuntimeAssetsOptions): SwissEphRuntimeAssetPaths;
/**
 * Initializes and returns the Swiss Ephemeris instance.
 * In a browser environment, assets are loaded relative to the script.
 * In Node.js, assets are loaded from the package's 'dist' directory.
 * @param options - Optional overrides for asset paths.
 * @param options.ephePath - Path to the directory containing ephemeris data files.
 * @param options.wasmPath - Path to the `swisseph.wasm` file.
 */
declare function getSwissEph(options?: {
    ephePath?: string;
    wasmPath?: string;
}): Promise<void>;
/**
 * Clean up Swiss Ephemeris resources
 */
declare function closeSwissEph(): void;

/**
 * Local civil time handling (DST-aware)
 * Convert a local date-time (given via IANA time zone, explicit UTC offset, or auto from lat/lon)
 * into a UTC Date for Swiss Ephemeris (which expects UT).
 */
interface LocalDateTimeParts {
    year: number;
    month: number;
    day: number;
    hour?: number;
    minute?: number;
    second?: number;
}
type TimeZoneOptions = {
    /**
     * IANA time zone
     * If provided, DST is handled automatically via Intl API.
     */
    timeZone?: string;
    /**
     * Explicit UTC offset in minutes for the local civil time.
     * Positive for east of Greenwich, negative for west (e.g., -180 for UTC-3).
     * If provided, overrides timeZone.
     */
    utcOffsetMinutes?: number;
    /**
     * Optional resolver to derive an IANA time zone from coordinates and date.
     * Use an external library (e.g., tz-lookup) and pass it here.
     */
    resolveTimeZone?: (latitude: number, longitude: number, local: LocalDateTimeParts) => string | undefined;
    /**
     * When true (default), try to auto-resolve the IANA time zone from lat/lon using tz-lookup
     * if no explicit offset/timeZone is provided.
     */
    autoTimeZone?: boolean;
    /**
     * When true, the date is treated as UTC instead of local civil time.
     */
    treatAsUTC?: boolean;
};

/**
 * Astro*Carto*Graphy (ACG) — locational astrology.
 *
 * Computes where each planet falls on the four angles (MC, IC, AC, DC)
 * across the globe, and queries a specific location for nearby lines
 * and paran crossings.
 *
 * MC/IC lines are pure math (GMST − RA). AC/DC lines require a latitude
 * sweep solving cos(H) = −tan(φ)·tan(δ).
 */

type AngleType = "MC" | "IC" | "AC" | "DC";
interface AstrocartographyLineProximity {
    planet: string;
    angle: AngleType;
    /** Degrees of longitude separation (always positive, 0-180). */
    distance: number;
    /** True when distance ≤ orb. */
    active: boolean;
    /** The line's geographic longitude at the query latitude (-180..180). */
    longitude: number;
}
interface AstrocartographyParan {
    latitude: number;
    planetA: string;
    angleA: AngleType;
    longitudeA: number;
    planetB: string;
    angleB: AngleType;
    longitudeB: number;
}
interface AstrocartographyQueryResult {
    queryLatitude: number;
    queryLongitude: number;
    orb: number;
    lines: AstrocartographyLineProximity[];
    activeLines: AstrocartographyLineProximity[];
    parans: AstrocartographyParan[];
}
interface AstrocartographyMeridianLine {
    planet: string;
    angle: "MC" | "IC";
    /** Geographic longitude (-180..180). */
    longitude: number;
}
interface AstrocartographyHorizonPoint {
    latitude: number;
    longitude: number;
}
interface AstrocartographyHorizonLine {
    planet: string;
    angle: "AC" | "DC";
    points: AstrocartographyHorizonPoint[];
}
interface AstrocartographyMap {
    meridianLines: AstrocartographyMeridianLine[];
    horizonLines: AstrocartographyHorizonLine[];
}
interface AstrocartographyMapOptions {
    /** Degrees between latitude sample points (default 1). */
    latitudeStep?: number;
    /** Maximum latitude to sweep (default 66.5). */
    latitudeRange?: number;
    /** Planets to include (default: ASTROCARTOGRAPHY_DEFAULT_PLANETS). */
    planets?: Planet[];
}
interface AstrocartographyQueryOptions {
    latitude: number;
    longitude: number;
    /** Orb in degrees (default 2). */
    orb?: number;
    /** Planets to include (default: ASTROCARTOGRAPHY_DEFAULT_PLANETS). */
    planets?: Planet[];
    /** Paran orb in degrees (default 1). */
    paranOrb?: number;
}
/** Default planet set for ACG (traditional + modern, no Lilith). */
declare const ASTROCARTOGRAPHY_DEFAULT_PLANETS: Planet[];
/**
 * Greenwich Mean Sidereal Time from Julian Day (degrees, 0-360).
 */
declare function computeGMST(julianDay: number): number;
/**
 * Geographic longitude where a planet's MC line falls.
 * Returns value in -180..180.
 */
declare function computeMCLongitude(gmst: number, ra: number): number;
/**
 * Geographic longitude where a planet's IC line falls (opposite MC).
 */
declare function computeICLongitude(gmst: number, ra: number): number;
/**
 * Geographic longitude where a planet rises (AC) or sets (DC)
 * at a given geographic latitude.
 *
 * Returns null if the planet is circumpolar or never rises at this latitude.
 */
declare function computeHorizonLongitude(gmst: number, ra: number, dec: number, latitude: number, angle: "AC" | "DC"): number | null;
/**
 * Shortest angular distance between two geographic longitudes.
 * Returns 0..180.
 */
declare function geographicAngularDifference(a: number, b: number): number;
interface PlanetEquatorial {
    ra: number;
    dec: number;
    planetId: Planet;
}
/**
 * Compute equatorial positions (RA/Dec) for a set of planets at a UTC date.
 */
declare function computeEquatorialPositions(date: Date, planets?: Planet[]): Record<string, PlanetEquatorial>;
/**
 * Find paran crossings at a given latitude.
 *
 * A paran exists when two different planet's angle-lines
 * pass through the same latitude within `paranOrb` degrees of longitude.
 */
declare function findParansAtLatitude(equatorialPositions: Record<string, PlanetEquatorial>, gmst: number, latitude: number, paranOrb?: number): AstrocartographyParan[];
/**
 * Query a specific location against a birth chart's ACG lines.
 *
 * Returns how close each planet's angle line is to the query location,
 * which lines are "active" (within orb), and paran crossings at the
 * query latitude.
 */
declare function queryAstrocartographyLocation(date: Date, options: AstrocartographyQueryOptions): AstrocartographyQueryResult;
/**
 * Generate the full ACG map: MC/IC lines (constant longitudes) and
 * AC/DC lines (arrays of lat/lon points from a latitude sweep).
 */
declare function computeAstrocartographyMap(date: Date, options?: AstrocartographyMapOptions): AstrocartographyMap;

type AspectName = "conjunction" | "duodecile" | "octile" | "sextile" | "square" | "trine" | "trioctile" | "quincunx" | "opposition";
interface AspectSpec {
    name: AspectName;
    angle: number;
    orb: number;
}
declare const DEFAULT_ASPECT_SPECS: AspectSpec[];
interface AspectEdge {
    planetA: string;
    planetB: string;
    longitudeA: number;
    longitudeB: number;
    aspect: AspectName;
    aspectAngle: number;
    delta: number;
    orb: number;
}
declare function getAspectMatch(lonA: number, lonB: number, specs?: AspectSpec[]): {
    spec: AspectSpec;
    orb: number;
    delta: number;
} | null;
declare function computeAspects(planets: Record<string, {
    longitude: number;
}>, specs?: AspectSpec[]): AspectEdge[];
declare function computeSynastryAspects(planetsA: Record<string, {
    longitude: number;
}>, planetsB: Record<string, {
    longitude: number;
}>, specs?: AspectSpec[]): AspectEdge[];
/** Shorter-arc midpoint of two ecliptic longitudes. */
declare function shorterArcMidpoint(a: number, b: number): number;
declare function computeMidpoints(planetsA: Record<string, {
    longitude: number;
}>, planetsB: Record<string, {
    longitude: number;
}>): Record<string, number>;
interface TransitAspectEdge extends AspectEdge {
    applying: boolean;
    retrograde: boolean;
    category: "slow" | "fast";
}
interface TransitAspectPoint {
    longitude: number;
    longitudeSpeed?: number;
}
declare const SLOW_PLANETS: Set<string>;
/**
 * Compute transit-to-natal aspects with applying/separating, retrograde, and speed category.
 *
 * planetA = transit planet, planetB = natal planet/point.
 */
declare function computeTransitAspects(transitPlanets: Record<string, TransitAspectPoint>, natalPlanets: Record<string, TransitAspectPoint>, specs?: AspectSpec[]): TransitAspectEdge[];

/**
 * Essential Dignity Table — Traditional Hellenistic rulership data.
 * Pure math, no WASM dependency.
 */

type Sign = (typeof SIGNS)[number];
type TraditionalPlanet = "Sun" | "Moon" | "Mercury" | "Venus" | "Mars" | "Jupiter" | "Saturn";
interface EssentialDignityResult {
    domicile: boolean;
    exaltation: boolean;
    detriment: boolean;
    fall: boolean;
    domicileRuler: TraditionalPlanet;
    peregrine: boolean;
}
declare const DOMICILE_RULERS: Record<Sign, TraditionalPlanet>;
declare const EXALTATIONS: Record<TraditionalPlanet, {
    sign: Sign;
    degree: number;
}>;
declare function getDomicileRuler(sign: Sign): TraditionalPlanet;
declare function getExaltation(planet: TraditionalPlanet): {
    sign: Sign;
    degree: number;
};
declare function getOppositeSign(sign: Sign): Sign;
/** Signs where the planet is in detriment (opposite of its domicile signs). */
declare function getDetriment(planet: TraditionalPlanet): Sign[];
/** Sign where the planet is in fall (opposite of its exaltation sign). */
declare function getFall(planet: TraditionalPlanet): Sign;
declare function getEssentialDignity(planet: TraditionalPlanet, sign: Sign): EssentialDignityResult;

/**
 * Decan (face) lookup — Chaldean rulers + Golden Dawn tarot correspondence.
 * Pure math, no WASM dependency.
 */

interface DecanResult {
    sign: string;
    decanNumber: 1 | 2 | 3;
    ruler: TraditionalPlanet;
    tarotCard: string;
    startDegree: number;
    endDegree: number;
    degreeWithinSign: number;
}
declare function getDecan(longitude: number): DecanResult;

/**
 * Dodecatemoria (12th parts) — traditional Hellenistic technique.
 * Pure math, no WASM dependency.
 */
interface DodecatemoriaResult {
    originalSign: string;
    originalDegree: number;
    dodecatemoriaSign: string;
    dodecatemoriaIndex: number;
}
declare function getDodecatemoria(longitude: number): DodecatemoriaResult;

/**
 * Annual & Monthly Profections — traditional Hellenistic time-lord technique.
 * Pure math. Requires a whole-sign BirthChart for house sign lookup.
 */

interface AnnualProfection {
    age: number;
    house: number;
    sign: string;
    ruler: TraditionalPlanet;
    targetYear: number;
}
interface MonthlyProfection {
    month: number;
    startDate: Date;
    sign: string;
    ruler: TraditionalPlanet;
}
interface MonthlyProfectionsResult {
    annualProfection: AnnualProfection;
    months: MonthlyProfection[];
}
declare function getAnnualProfection(natalChart: BirthChart, birthDate: Date, targetYear?: number): AnnualProfection;
declare function getMonthlyProfections(natalChart: BirthChart, birthDate: Date, targetYear?: number): MonthlyProfectionsResult;

/**
 * Firdaria — traditional planetary period system.
 * Pure math, no WASM dependency.
 */
type FirdariaPlanet = "Sun" | "Moon" | "Mercury" | "Venus" | "Mars" | "Jupiter" | "Saturn" | "NorthNode" | "SouthNode";
interface FirdariaSubPeriod {
    planet: FirdariaPlanet;
    startDate: Date;
    endDate: Date;
}
interface FirdariaMajorPeriod {
    planet: FirdariaPlanet;
    years: number;
    startDate: Date;
    endDate: Date;
    subPeriods: FirdariaSubPeriod[];
}
interface FirdariaResult {
    sect: "diurnal" | "nocturnal";
    currentMajor: FirdariaMajorPeriod;
    currentSub: FirdariaSubPeriod;
    allPeriods: FirdariaMajorPeriod[];
}
interface FirdariaOptions {
    nodeSubPeriodStart?: "jupiter-saturn" | "sun-mars";
}
declare function getFirdaria(birthDate: Date, isDiurnal: boolean, targetDate?: Date, options?: FirdariaOptions): FirdariaResult;

/**
 * Astrological calculations using Swiss Ephemeris
 */

interface BirthChartOptions {
    /**
     * Local civil date-time for the chart moment.
     * Prefer `LocalDateTimeParts` when the source data comes from separate
     * date/time inputs so callers do not have to encode wall-clock parts into a
     * browser-local `Date`.
     */
    date: Date | LocalDateTimeParts;
    latitude: number;
    longitude: number;
    houseSystem?: HouseSystem;
    timeZoneSettings?: TimeZoneOptions;
}
type ZodiacPosition = {
    sign: string;
    decimalDegrees: number;
    traditionalFormat: string;
    decimal: string;
    longitude: number;
    house: number;
};
type HydratedNode = ZodiacPosition & {
    id: VirtualNodes;
    name: string;
};
type HydratedPlanet = PlanetPosition & {
    id: Planet;
    name: string;
    zodiacPosition: ZodiacPosition;
};
interface BirthChart {
    dateUtc: Date;
    planets: Record<string, HydratedPlanet>;
    nodes: Record<string, HydratedNode>;
    houses: {
        ascendant: ZodiacPosition;
        mc: ZodiacPosition;
        dc: ZodiacPosition;
        ic: ZodiacPosition;
        houses: ZodiacPosition[];
        ascmc?: {
            armc?: ZodiacPosition;
            vertex?: ZodiacPosition;
            equasc?: ZodiacPosition;
            coasc1?: ZodiacPosition;
            coasc2?: ZodiacPosition;
            polasc?: ZodiacPosition;
        };
    };
    aspects: AspectEdge[];
    sect: "diurnal" | "nocturnal";
}
/**
 * Calculate a birth chart using Swiss Ephemeris
 *
 * @param options Chart calculation options
 * @returns Birth chart data
 */
declare function getBirthChart(options: BirthChartOptions): Promise<BirthChart>;
declare const SIGNS: readonly ["Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra", "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces"];
/**
 * Convert decimal degrees to degrees and minutes format
 *
 * @param decimalDegrees Decimal degrees (e.g., 9.8)
 * @returns Formatted string (e.g., "9°48'")
 */
declare function formatDegreeMinutes(decimalDegrees: number): string;
/**
 * Convert decimal degrees to zodiac position (sign and degrees)
 *
 * @param longitude Longitude in decimal degrees (0-360)
 * @returns Formatted zodiac position with both decimal and traditional format
 */
declare function getZodiacPosition(longitude: number, houseCusps: number[]): ZodiacPosition;
declare function findHouseOf(longitude: number, housePositions: number[]): number;
interface TwoChartOptions {
    chartA: BirthChartOptions;
    chartB: BirthChartOptions;
    aspectSpecs?: AspectSpec[];
}
type SynastryChartOptions = TwoChartOptions;
type CompositeChartOptions = TwoChartOptions;
interface SynastryChart {
    chartA: BirthChart;
    chartB: BirthChart;
    aspects: AspectEdge[];
}
interface CompositeChart {
    chartA: BirthChart;
    chartB: BirthChart;
    compositePlanets: Record<string, {
        name: string;
        longitude: number;
        zodiacPosition: ZodiacPosition;
    }>;
    compositeHouses: ZodiacPosition[];
    aspects: AspectEdge[];
}
declare function getSynastryChart(options: SynastryChartOptions): Promise<SynastryChart>;
declare function getCompositeChart(options: CompositeChartOptions): Promise<CompositeChart>;
interface TransitChartOptions {
    natal: BirthChartOptions;
    transitDate: Date;
    transitLatitude?: number;
    transitLongitude?: number;
    transitTimeZoneSettings?: TimeZoneOptions;
    aspectSpecs?: AspectSpec[];
    maxOrb?: number;
    transitPlanets?: string[];
    natalPlanets?: string[];
    aspectFilter?: AspectName[];
}
interface TransitPlanet extends HydratedPlanet {
    retrograde: boolean;
    natalHouse: number;
}
interface TransitChart {
    natalChart: BirthChart;
    transitDateUtc: Date;
    transitPlanets: Record<string, TransitPlanet>;
    aspects: TransitAspectEdge[];
}
interface TransitRangeOptions extends Omit<TransitChartOptions, "transitDate"> {
    from: Date;
    to: Date;
    stepDays?: number;
}
interface AspectPerfection {
    transitPlanet: string;
    natalPlanet: string;
    aspect: AspectName;
    exactDate: Date;
    exactOrb: number;
    retrograde: boolean;
    category: "slow" | "fast";
}
interface TransitRangeResult {
    natalChart: BirthChart;
    from: Date;
    to: Date;
    perfections: AspectPerfection[];
}
declare function getTransitChart(options: TransitChartOptions): Promise<TransitChart>;
declare function getTransitRange(options: TransitRangeOptions): Promise<TransitRangeResult>;
interface SolarReturnOptions {
    natal: BirthChartOptions;
    year: number;
    solarReturnLatitude?: number;
    solarReturnLongitude?: number;
    solarReturnHouseSystem?: HouseSystem;
}
interface SolarReturnChart {
    natalChart: BirthChart;
    solarReturnChart: BirthChart;
    exactReturnDate: Date;
    natalSunLongitude: number;
    year: number;
}
/**
 * Calculate a Solar Return chart — the moment the transiting Sun returns
 * to its natal longitude in the given year.
 */
declare function getSolarReturnChart(options: SolarReturnOptions): Promise<SolarReturnChart>;

export { ASTROCARTOGRAPHY_DEFAULT_PLANETS, type AngleType, type AnnualProfection, type AspectEdge, type AspectName, type AspectPerfection, type AspectSpec, type AstrocartographyHorizonLine, type AstrocartographyHorizonPoint, type AstrocartographyLineProximity, type AstrocartographyMap, type AstrocartographyMapOptions, type AstrocartographyMeridianLine, type AstrocartographyParan, type AstrocartographyQueryOptions, type AstrocartographyQueryResult, type AzaltResult, type BirthChart, type BirthChartOptions, CalcFlag, type CompositeChart, type CompositeChartOptions, DEFAULT_ASPECT_SPECS, DOMICILE_RULERS, type DecanResult, type DodecatemoriaResult, EXALTATIONS, type EssentialDignityResult, type FirdariaMajorPeriod, type FirdariaOptions, type FirdariaPlanet, type FirdariaResult, type FirdariaSubPeriod, HouseSystem, type HydratedNode, type HydratedPlanet, type LocalDateTimeParts, type MonthlyProfection, type MonthlyProfectionsResult, PLANET_AND_NODE_NAMES, Planet, type PlanetEquatorial, type ResolveSwissEphRuntimeAssetsOptions, RiseTransitFlag, SIGNS, SLOW_PLANETS, type Sign, type SolarReturnChart, type SolarReturnOptions, type SwissEphRuntimeAssetPaths, type SynastryChart, type SynastryChartOptions, type TraditionalPlanet, type TransitAspectEdge, type TransitAspectPoint, type TransitChart, type TransitChartOptions, type TransitPlanet, type TransitRangeOptions, type TransitRangeResult, type TwoChartOptions, VirtualNodes, type ZodiacPosition, closeSwissEph, computeAspects, computeAstrocartographyMap, computeEquatorialPositions, computeGMST, computeHorizonLongitude, computeICLongitude, computeMCLongitude, computeMidpoints, computeSynastryAspects, computeTransitAspects, findHouseOf, findParansAtLatitude, formatDegreeMinutes, geographicAngularDifference, getAnnualProfection, getAspectMatch, getBirthChart, getCompositeChart, getDecan, getDetriment, getDodecatemoria, getDomicileRuler, getEssentialDignity, getExaltation, getFall, getFirdaria, getMonthlyProfections, getOppositeSign, getSolarReturnChart, getSwissEph, getSynastryChart, getTransitChart, getTransitRange, getZodiacPosition, normalizeAngle, queryAstrocartographyLocation, resolveSwissEphRuntimeAssets, shorterArcMidpoint };