kaabalah 5.3.0 → 5.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -50,6 +50,19 @@ declare enum CalcFlag {
50
50
  TOPOCTR = 32768,
51
51
  SIDEREAL = 65536
52
52
  }
53
+ declare enum RiseTransitFlag {
54
+ RISE = 1,
55
+ SET = 2,
56
+ UPPER_MERIDIAN = 4,
57
+ LOWER_MERIDIAN = 8,
58
+ DISC_CENTER = 256,
59
+ NO_REFRACTION = 512
60
+ }
61
+ interface AzaltResult {
62
+ azimuth: number;
63
+ trueAltitude: number;
64
+ apparentAltitude: number;
65
+ }
53
66
  interface PlanetPosition {
54
67
  longitude: number;
55
68
  latitude: number;
@@ -118,6 +131,139 @@ type TimeZoneOptions = {
118
131
  treatAsUTC?: boolean;
119
132
  };
120
133
 
134
+ /**
135
+ * Astro*Carto*Graphy (ACG) — locational astrology.
136
+ *
137
+ * Computes where each planet falls on the four angles (MC, IC, AC, DC)
138
+ * across the globe, and queries a specific location for nearby lines
139
+ * and paran crossings.
140
+ *
141
+ * MC/IC lines are pure math (GMST − RA). AC/DC lines require a latitude
142
+ * sweep solving cos(H) = −tan(φ)·tan(δ).
143
+ */
144
+
145
+ type AngleType = "MC" | "IC" | "AC" | "DC";
146
+ interface AstrocartographyLineProximity {
147
+ planet: string;
148
+ angle: AngleType;
149
+ /** Degrees of longitude separation (always positive, 0-180). */
150
+ distance: number;
151
+ /** True when distance ≤ orb. */
152
+ active: boolean;
153
+ /** The line's geographic longitude at the query latitude (-180..180). */
154
+ longitude: number;
155
+ }
156
+ interface AstrocartographyParan {
157
+ latitude: number;
158
+ planetA: string;
159
+ angleA: AngleType;
160
+ longitudeA: number;
161
+ planetB: string;
162
+ angleB: AngleType;
163
+ longitudeB: number;
164
+ }
165
+ interface AstrocartographyQueryResult {
166
+ queryLatitude: number;
167
+ queryLongitude: number;
168
+ orb: number;
169
+ lines: AstrocartographyLineProximity[];
170
+ activeLines: AstrocartographyLineProximity[];
171
+ parans: AstrocartographyParan[];
172
+ }
173
+ interface AstrocartographyMeridianLine {
174
+ planet: string;
175
+ angle: "MC" | "IC";
176
+ /** Geographic longitude (-180..180). */
177
+ longitude: number;
178
+ }
179
+ interface AstrocartographyHorizonPoint {
180
+ latitude: number;
181
+ longitude: number;
182
+ }
183
+ interface AstrocartographyHorizonLine {
184
+ planet: string;
185
+ angle: "AC" | "DC";
186
+ points: AstrocartographyHorizonPoint[];
187
+ }
188
+ interface AstrocartographyMap {
189
+ meridianLines: AstrocartographyMeridianLine[];
190
+ horizonLines: AstrocartographyHorizonLine[];
191
+ }
192
+ interface AstrocartographyMapOptions {
193
+ /** Degrees between latitude sample points (default 1). */
194
+ latitudeStep?: number;
195
+ /** Maximum latitude to sweep (default 66.5). */
196
+ latitudeRange?: number;
197
+ /** Planets to include (default: ASTROCARTOGRAPHY_DEFAULT_PLANETS). */
198
+ planets?: Planet[];
199
+ }
200
+ interface AstrocartographyQueryOptions {
201
+ latitude: number;
202
+ longitude: number;
203
+ /** Orb in degrees (default 2). */
204
+ orb?: number;
205
+ /** Planets to include (default: ASTROCARTOGRAPHY_DEFAULT_PLANETS). */
206
+ planets?: Planet[];
207
+ /** Paran orb in degrees (default 1). */
208
+ paranOrb?: number;
209
+ }
210
+ /** Default planet set for ACG (traditional + modern, no Lilith). */
211
+ declare const ASTROCARTOGRAPHY_DEFAULT_PLANETS: Planet[];
212
+ /**
213
+ * Greenwich Mean Sidereal Time from Julian Day (degrees, 0-360).
214
+ */
215
+ declare function computeGMST(julianDay: number): number;
216
+ /**
217
+ * Geographic longitude where a planet's MC line falls.
218
+ * Returns value in -180..180.
219
+ */
220
+ declare function computeMCLongitude(gmst: number, ra: number): number;
221
+ /**
222
+ * Geographic longitude where a planet's IC line falls (opposite MC).
223
+ */
224
+ declare function computeICLongitude(gmst: number, ra: number): number;
225
+ /**
226
+ * Geographic longitude where a planet rises (AC) or sets (DC)
227
+ * at a given geographic latitude.
228
+ *
229
+ * Returns null if the planet is circumpolar or never rises at this latitude.
230
+ */
231
+ declare function computeHorizonLongitude(gmst: number, ra: number, dec: number, latitude: number, angle: "AC" | "DC"): number | null;
232
+ /**
233
+ * Shortest angular distance between two geographic longitudes.
234
+ * Returns 0..180.
235
+ */
236
+ declare function geographicAngularDifference(a: number, b: number): number;
237
+ interface PlanetEquatorial {
238
+ ra: number;
239
+ dec: number;
240
+ planetId: Planet;
241
+ }
242
+ /**
243
+ * Compute equatorial positions (RA/Dec) for a set of planets at a UTC date.
244
+ */
245
+ declare function computeEquatorialPositions(date: Date, planets?: Planet[]): Record<string, PlanetEquatorial>;
246
+ /**
247
+ * Find paran crossings at a given latitude.
248
+ *
249
+ * A paran exists when two different planet's angle-lines
250
+ * pass through the same latitude within `paranOrb` degrees of longitude.
251
+ */
252
+ declare function findParansAtLatitude(equatorialPositions: Record<string, PlanetEquatorial>, gmst: number, latitude: number, paranOrb?: number): AstrocartographyParan[];
253
+ /**
254
+ * Query a specific location against a birth chart's ACG lines.
255
+ *
256
+ * Returns how close each planet's angle line is to the query location,
257
+ * which lines are "active" (within orb), and paran crossings at the
258
+ * query latitude.
259
+ */
260
+ declare function queryAstrocartographyLocation(date: Date, options: AstrocartographyQueryOptions): AstrocartographyQueryResult;
261
+ /**
262
+ * Generate the full ACG map: MC/IC lines (constant longitudes) and
263
+ * AC/DC lines (arrays of lat/lon points from a latitude sweep).
264
+ */
265
+ declare function computeAstrocartographyMap(date: Date, options?: AstrocartographyMapOptions): AstrocartographyMap;
266
+
121
267
  type AspectName = "conjunction" | "duodecile" | "octile" | "sextile" | "square" | "trine" | "trioctile" | "quincunx" | "opposition";
122
268
  interface AspectSpec {
123
269
  name: AspectName;
@@ -155,6 +301,135 @@ declare function computeMidpoints(planetsA: Record<string, {
155
301
  }>, planetsB: Record<string, {
156
302
  longitude: number;
157
303
  }>): Record<string, number>;
304
+ interface TransitAspectEdge extends AspectEdge {
305
+ applying: boolean;
306
+ retrograde: boolean;
307
+ category: "slow" | "fast";
308
+ }
309
+ interface TransitAspectPoint {
310
+ longitude: number;
311
+ longitudeSpeed?: number;
312
+ }
313
+ declare const SLOW_PLANETS: Set<string>;
314
+ /**
315
+ * Compute transit-to-natal aspects with applying/separating, retrograde, and speed category.
316
+ *
317
+ * planetA = transit planet, planetB = natal planet/point.
318
+ */
319
+ declare function computeTransitAspects(transitPlanets: Record<string, TransitAspectPoint>, natalPlanets: Record<string, TransitAspectPoint>, specs?: AspectSpec[]): TransitAspectEdge[];
320
+
321
+ /**
322
+ * Essential Dignity Table — Traditional Hellenistic rulership data.
323
+ * Pure math, no WASM dependency.
324
+ */
325
+
326
+ type Sign = (typeof SIGNS)[number];
327
+ type TraditionalPlanet = "Sun" | "Moon" | "Mercury" | "Venus" | "Mars" | "Jupiter" | "Saturn";
328
+ interface EssentialDignityResult {
329
+ domicile: boolean;
330
+ exaltation: boolean;
331
+ detriment: boolean;
332
+ fall: boolean;
333
+ domicileRuler: TraditionalPlanet;
334
+ peregrine: boolean;
335
+ }
336
+ declare const DOMICILE_RULERS: Record<Sign, TraditionalPlanet>;
337
+ declare const EXALTATIONS: Record<TraditionalPlanet, {
338
+ sign: Sign;
339
+ degree: number;
340
+ }>;
341
+ declare function getDomicileRuler(sign: Sign): TraditionalPlanet;
342
+ declare function getExaltation(planet: TraditionalPlanet): {
343
+ sign: Sign;
344
+ degree: number;
345
+ };
346
+ declare function getOppositeSign(sign: Sign): Sign;
347
+ /** Signs where the planet is in detriment (opposite of its domicile signs). */
348
+ declare function getDetriment(planet: TraditionalPlanet): Sign[];
349
+ /** Sign where the planet is in fall (opposite of its exaltation sign). */
350
+ declare function getFall(planet: TraditionalPlanet): Sign;
351
+ declare function getEssentialDignity(planet: TraditionalPlanet, sign: Sign): EssentialDignityResult;
352
+
353
+ /**
354
+ * Decan (face) lookup — Chaldean rulers + Golden Dawn tarot correspondence.
355
+ * Pure math, no WASM dependency.
356
+ */
357
+
358
+ interface DecanResult {
359
+ sign: string;
360
+ decanNumber: 1 | 2 | 3;
361
+ ruler: TraditionalPlanet;
362
+ tarotCard: string;
363
+ startDegree: number;
364
+ endDegree: number;
365
+ degreeWithinSign: number;
366
+ }
367
+ declare function getDecan(longitude: number): DecanResult;
368
+
369
+ /**
370
+ * Dodecatemoria (12th parts) — traditional Hellenistic technique.
371
+ * Pure math, no WASM dependency.
372
+ */
373
+ interface DodecatemoriaResult {
374
+ originalSign: string;
375
+ originalDegree: number;
376
+ dodecatemoriaSign: string;
377
+ dodecatemoriaIndex: number;
378
+ }
379
+ declare function getDodecatemoria(longitude: number): DodecatemoriaResult;
380
+
381
+ /**
382
+ * Annual & Monthly Profections — traditional Hellenistic time-lord technique.
383
+ * Pure math. Requires a whole-sign BirthChart for house sign lookup.
384
+ */
385
+
386
+ interface AnnualProfection {
387
+ age: number;
388
+ house: number;
389
+ sign: string;
390
+ ruler: TraditionalPlanet;
391
+ targetYear: number;
392
+ }
393
+ interface MonthlyProfection {
394
+ month: number;
395
+ startDate: Date;
396
+ sign: string;
397
+ ruler: TraditionalPlanet;
398
+ }
399
+ interface MonthlyProfectionsResult {
400
+ annualProfection: AnnualProfection;
401
+ months: MonthlyProfection[];
402
+ }
403
+ declare function getAnnualProfection(natalChart: BirthChart, birthDate: Date, targetYear?: number): AnnualProfection;
404
+ declare function getMonthlyProfections(natalChart: BirthChart, birthDate: Date, targetYear?: number): MonthlyProfectionsResult;
405
+
406
+ /**
407
+ * Firdaria — traditional planetary period system.
408
+ * Pure math, no WASM dependency.
409
+ */
410
+ type FirdariaPlanet = "Sun" | "Moon" | "Mercury" | "Venus" | "Mars" | "Jupiter" | "Saturn" | "NorthNode" | "SouthNode";
411
+ interface FirdariaSubPeriod {
412
+ planet: FirdariaPlanet;
413
+ startDate: Date;
414
+ endDate: Date;
415
+ }
416
+ interface FirdariaMajorPeriod {
417
+ planet: FirdariaPlanet;
418
+ years: number;
419
+ startDate: Date;
420
+ endDate: Date;
421
+ subPeriods: FirdariaSubPeriod[];
422
+ }
423
+ interface FirdariaResult {
424
+ sect: "diurnal" | "nocturnal";
425
+ currentMajor: FirdariaMajorPeriod;
426
+ currentSub: FirdariaSubPeriod;
427
+ allPeriods: FirdariaMajorPeriod[];
428
+ }
429
+ interface FirdariaOptions {
430
+ nodeSubPeriodStart?: "jupiter-saturn" | "sun-mars";
431
+ }
432
+ declare function getFirdaria(birthDate: Date, isDiurnal: boolean, targetDate?: Date, options?: FirdariaOptions): FirdariaResult;
158
433
 
159
434
  /**
160
435
  * Astrological calculations using Swiss Ephemeris
@@ -204,6 +479,7 @@ interface BirthChart {
204
479
  };
205
480
  };
206
481
  aspects: AspectEdge[];
482
+ sect: "diurnal" | "nocturnal";
207
483
  }
208
484
  /**
209
485
  * Calculate a birth chart using Swiss Ephemeris
@@ -253,5 +529,68 @@ interface CompositeChart {
253
529
  }
254
530
  declare function getSynastryChart(options: SynastryChartOptions): Promise<SynastryChart>;
255
531
  declare function getCompositeChart(options: CompositeChartOptions): Promise<CompositeChart>;
532
+ interface TransitChartOptions {
533
+ natal: BirthChartOptions;
534
+ transitDate: Date;
535
+ transitLatitude?: number;
536
+ transitLongitude?: number;
537
+ transitTimeZoneSettings?: TimeZoneOptions;
538
+ aspectSpecs?: AspectSpec[];
539
+ maxOrb?: number;
540
+ transitPlanets?: string[];
541
+ natalPlanets?: string[];
542
+ aspectFilter?: AspectName[];
543
+ }
544
+ interface TransitPlanet extends HydratedPlanet {
545
+ retrograde: boolean;
546
+ natalHouse: number;
547
+ }
548
+ interface TransitChart {
549
+ natalChart: BirthChart;
550
+ transitDateUtc: Date;
551
+ transitPlanets: Record<string, TransitPlanet>;
552
+ aspects: TransitAspectEdge[];
553
+ }
554
+ interface TransitRangeOptions extends Omit<TransitChartOptions, "transitDate"> {
555
+ from: Date;
556
+ to: Date;
557
+ stepDays?: number;
558
+ }
559
+ interface AspectPerfection {
560
+ transitPlanet: string;
561
+ natalPlanet: string;
562
+ aspect: AspectName;
563
+ exactDate: Date;
564
+ exactOrb: number;
565
+ retrograde: boolean;
566
+ category: "slow" | "fast";
567
+ }
568
+ interface TransitRangeResult {
569
+ natalChart: BirthChart;
570
+ from: Date;
571
+ to: Date;
572
+ perfections: AspectPerfection[];
573
+ }
574
+ declare function getTransitChart(options: TransitChartOptions): Promise<TransitChart>;
575
+ declare function getTransitRange(options: TransitRangeOptions): Promise<TransitRangeResult>;
576
+ interface SolarReturnOptions {
577
+ natal: BirthChartOptions;
578
+ year: number;
579
+ solarReturnLatitude?: number;
580
+ solarReturnLongitude?: number;
581
+ solarReturnHouseSystem?: HouseSystem;
582
+ }
583
+ interface SolarReturnChart {
584
+ natalChart: BirthChart;
585
+ solarReturnChart: BirthChart;
586
+ exactReturnDate: Date;
587
+ natalSunLongitude: number;
588
+ year: number;
589
+ }
590
+ /**
591
+ * Calculate a Solar Return chart — the moment the transiting Sun returns
592
+ * to its natal longitude in the given year.
593
+ */
594
+ declare function getSolarReturnChart(options: SolarReturnOptions): Promise<SolarReturnChart>;
256
595
 
257
- export { type AspectEdge, type AspectName, type AspectSpec, type BirthChart, type BirthChartOptions, CalcFlag, type CompositeChart, type CompositeChartOptions, DEFAULT_ASPECT_SPECS, HouseSystem, type HydratedNode, type HydratedPlanet, PLANET_AND_NODE_NAMES, Planet, SIGNS, type SynastryChart, type SynastryChartOptions, type TwoChartOptions, VirtualNodes, type ZodiacPosition, closeSwissEph, computeAspects, computeMidpoints, computeSynastryAspects, findHouseOf, formatDegreeMinutes, getAspectMatch, getBirthChart, getCompositeChart, getSwissEph, getSynastryChart, getZodiacPosition, normalizeAngle, shorterArcMidpoint };
596
+ 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 MonthlyProfection, type MonthlyProfectionsResult, PLANET_AND_NODE_NAMES, Planet, type PlanetEquatorial, RiseTransitFlag, SIGNS, SLOW_PLANETS, type Sign, type SolarReturnChart, type SolarReturnOptions, 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, shorterArcMidpoint };