chart2txt 0.5.2 → 0.7.0

package/dist/types.d.ts

@@ -17,30 +17,176 @@ export interface ChartData {
 }
 export type MultiChartData = ChartData[];
 export declare function isMultiChartData(obj: ChartData | MultiChartData): obj is MultiChartData;
+export type UnionedPoint = [Point, string];
+export declare enum AspectClassification {
+    Major = "major",
+    Minor = "minor",
+    Esoteric = "esoteric"
+}
+export declare enum PlanetCategory {
+    Luminaries = "luminaries",
+    Personal = "personal",
+    Social = "social",
+    Outer = "outer",
+    Angles = "angles"
+}
 export interface Aspect {
     name: string;
     angle: number;
     orb: number;
+    classification?: AspectClassification;
+}
+export type AspectStrength = 'tight' | 'moderate' | 'wide';
+export interface AspectStrengthThresholds {
+    tight: number;
+    moderate: number;
 }
 export interface AspectData {
     planetA: string;
     planetB: string;
+    p1ChartName?: string;
+    p2ChartName?: string;
     aspectType: string;
     orb: number;
+    application?: 'applying' | 'separating' | 'exact';
 }
-export interface AspectCategory {
+export interface PlanetPosition {
     name: string;
-    minOrb?: number;
-    maxOrb: number;
-}
-export interface Settings {
-    includeSignDegree: boolean;
-    includeAscendant: boolean;
-    houseSystemName: string;
-    includeHouseDegree: boolean;
-    aspectDefinitions: Aspect[];
-    aspectCategories: AspectCategory[];
-    skipOutOfSignAspects: boolean;
-    dateFormat: string;
+    degree: number;
+    sign: string;
+    speed?: number;
+    house?: number;
+    chartName?: string;
+}
+export interface TSquare {
+    type: 'T-Square';
+    apex: PlanetPosition;
+    opposition: [PlanetPosition, PlanetPosition];
+    mode: 'Cardinal' | 'Fixed' | 'Mutable';
+    averageOrb: number;
+}
+export interface GrandTrine {
+    type: 'Grand Trine';
+    planets: [PlanetPosition, PlanetPosition, PlanetPosition];
+    element: 'Fire' | 'Earth' | 'Air' | 'Water';
+    averageOrb: number;
+}
+export interface Stellium {
+    type: 'Stellium';
+    planets: PlanetPosition[];
+    sign?: string;
+    houses: number[];
+    span: number;
+}
+export interface GrandCross {
+    type: 'Grand Cross';
+    planets: [PlanetPosition, PlanetPosition, PlanetPosition, PlanetPosition];
+    mode: 'Cardinal' | 'Fixed' | 'Mutable';
+    averageOrb: number;
+}
+export interface Yod {
+    type: 'Yod';
+    apex: PlanetPosition;
+    base: [PlanetPosition, PlanetPosition];
+    averageOrb: number;
+}
+export interface MysticRectangle {
+    type: 'Mystic Rectangle';
+    oppositions: [
+        [
+            PlanetPosition,
+            PlanetPosition
+        ],
+        [
+            PlanetPosition,
+            PlanetPosition
+        ]
+    ];
+    averageOrb: number;
+}
+export interface Kite {
+    type: 'Kite';
+    grandTrine: [PlanetPosition, PlanetPosition, PlanetPosition];
+    opposition: PlanetPosition;
+    averageOrb: number;
+}
+export type AspectPattern = TSquare | GrandTrine | Stellium | GrandCross | Yod | MysticRectangle | Kite;
+export interface ChartAnalysis {
+    chart: ChartData;
+    placements: {
+        planets: PlanetPosition[];
+        [key: string]: any;
+    };
+    aspects: AspectData[];
+    groupedAspects?: Map<string, AspectData[]>;
+    patterns: AspectPattern[];
+    stelliums: Stellium[];
+    signDistributions: {
+        elements: {
+            [key: string]: string[];
+        };
+        modalities: {
+            [key: string]: number;
+        };
+        polarities: {
+            [key: string]: number;
+        };
+    };
+    dispositors: {
+        [key: string]: string;
+    };
+}
+export interface PairwiseAnalysis {
+    chart1: ChartData;
+    chart2: ChartData;
+    synastryAspects: AspectData[];
+    groupedSynastryAspects?: Map<string, AspectData[]>;
+    compositePatterns: AspectPattern[];
+    houseOverlays: {
+        chart1InChart2Houses: {
+            [key: string]: number;
+        };
+        chart2InChart1Houses: {
+            [key: string]: number;
+        };
+    };
+}
+export interface GlobalAnalysis {
+    charts: ChartData[];
+    patterns: AspectPattern[];
+}
+export interface TransitAnalysis {
+    natalChart: ChartData;
+    transitChart: ChartData;
+    aspects: AspectData[];
+    groupedAspects?: Map<string, AspectData[]>;
+    patterns: AspectPattern[];
+}
+export interface AstrologicalReport {
+    settings: Settings;
+    chartAnalyses: ChartAnalysis[];
+    pairwiseAnalyses: PairwiseAnalysis[];
+    globalAnalysis?: GlobalAnalysis;
+    transitAnalyses: TransitAnalysis[];
+    globalTransitAnalysis?: GlobalAnalysis;
+}
+export interface AnalysisSettings {
+    aspectDefinitions?: Aspect[] | 'traditional' | 'modern' | 'tight' | 'wide';
+    skipOutOfSignAspects?: boolean;
+    includeAspectPatterns?: boolean;
+    includeSignDistributions?: boolean;
+}
+export interface GroupingSettings {
+    aspectStrengthThresholds?: AspectStrengthThresholds;
+}
+export interface FormattingSettings {
+    dateFormat?: string;
+    houseSystemName?: string;
+}
+export interface Settings extends AnalysisSettings, GroupingSettings, FormattingSettings {
 }
 export type PartialSettings = Partial<Settings>;
+export type ChartDataWithInfo = {
+    data: ChartData;
+    index: number;
+};

package/dist/types.js

@@ -1,6 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlanetCategory = exports.AspectClassification = void 0;
 exports.isMultiChartData = isMultiChartData;
 function isMultiChartData(obj) {
     return Array.isArray(obj);
 }
+var AspectClassification;
+(function (AspectClassification) {
+    AspectClassification["Major"] = "major";
+    AspectClassification["Minor"] = "minor";
+    AspectClassification["Esoteric"] = "esoteric";
+})(AspectClassification || (exports.AspectClassification = AspectClassification = {}));
+var PlanetCategory;
+(function (PlanetCategory) {
+    PlanetCategory["Luminaries"] = "luminaries";
+    PlanetCategory["Personal"] = "personal";
+    PlanetCategory["Social"] = "social";
+    PlanetCategory["Outer"] = "outer";
+    PlanetCategory["Angles"] = "angles";
+})(PlanetCategory || (exports.PlanetCategory = PlanetCategory = {}));

package/dist/utils/formatting.d.ts

@@ -0,0 +1,10 @@
+import { Point, PlanetPosition } from '../types';
+/**
+ * Converts a number to its ordinal form (1st, 2nd, 3rd, etc.)
+ * @param num The number to convert
+ * @returns The ordinal string
+ */
+export declare function getOrdinal(num: number): string;
+export declare function getSign(degree: number): string;
+export declare function getHouse(degree: number, houseCusps: number[]): number;
+export declare function getPlanetPositions(planets: Point[], houseCusps?: number[]): PlanetPosition[];

package/dist/utils/formatting.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOrdinal = getOrdinal;
+exports.getSign = getSign;
+exports.getHouse = getHouse;
+exports.getPlanetPositions = getPlanetPositions;
+const constants_1 = require("../constants");
+function normalizeDegree(degree) {
+    return ((degree % 360) + 360) % 360;
+}
+/**
+ * Converts a number to its ordinal form (1st, 2nd, 3rd, etc.)
+ * @param num The number to convert
+ * @returns The ordinal string
+ */
+function getOrdinal(num) {
+    const suffix = ['th', 'st', 'nd', 'rd'];
+    const v = num % 100;
+    return num + (suffix[(v - 20) % 10] || suffix[v] || suffix[0]);
+}
+function getSign(degree) {
+    const signIndex = Math.floor(degree / 30);
+    return constants_1.ZODIAC_SIGNS[signIndex];
+}
+function getHouse(degree, houseCusps) {
+    for (let i = 0; i < 12; i++) {
+        const cusp1 = houseCusps[i];
+        const cusp2 = houseCusps[(i + 1) % 12];
+        if (cusp1 < cusp2) {
+            if (degree >= cusp1 && degree < cusp2) {
+                return i + 1;
+            }
+        }
+        else {
+            if (degree >= cusp1 || degree < cusp2) {
+                return i + 1;
+            }
+        }
+    }
+    return -1; // Should not happen
+}
+function getPlanetPositions(planets, houseCusps) {
+    return planets.map((planet) => {
+        const normalizedDegree = normalizeDegree(planet.degree);
+        const position = {
+            name: planet.name,
+            degree: normalizedDegree,
+            sign: getSign(normalizedDegree),
+            speed: planet.speed,
+        };
+        if (houseCusps) {
+            position.house = getHouse(normalizedDegree, houseCusps);
+        }
+        return position;
+    });
+}

package/dist/utils/houseCalculations.d.ts

@@ -0,0 +1,10 @@
+import { ChartData } from '../types';
+export declare function calculateHouseOverlays(chart1: ChartData, chart2: ChartData): {
+    chart1InChart2Houses: {
+        [key: string]: number;
+    };
+    chart2InChart1Houses: {
+        [key: string]: number;
+    };
+};
+export declare function getHouseForPoint(degree: number, houseCusps: number[]): number;

package/dist/utils/houseCalculations.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateHouseOverlays = calculateHouseOverlays;
+exports.getHouseForPoint = getHouseForPoint;
+const formatting_1 = require("./formatting");
+function calculateHouseOverlays(chart1, chart2) {
+    const chart1InChart2Houses = {};
+    if (chart2.houseCusps) {
+        for (const planet of chart1.planets) {
+            chart1InChart2Houses[planet.name] = (0, formatting_1.getHouse)(planet.degree, chart2.houseCusps);
+        }
+    }
+    const chart2InChart1Houses = {};
+    if (chart1.houseCusps) {
+        for (const planet of chart2.planets) {
+            chart2InChart1Houses[planet.name] = (0, formatting_1.getHouse)(planet.degree, chart1.houseCusps);
+        }
+    }
+    return { chart1InChart2Houses, chart2InChart1Houses };
+}
+function getHouseForPoint(degree, houseCusps) {
+    return (0, formatting_1.getHouse)(degree, houseCusps);
+}

package/dist/utils/precision.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Floating point precision utilities for astrological calculations
+ */
+export declare const DEFAULT_EPSILON = 0.0001;
+/**
+ * Compares two floating-point numbers with epsilon tolerance
+ * @param a First number
+ * @param b Second number
+ * @param epsilon Tolerance value (default: DEFAULT_EPSILON)
+ * @returns True if numbers are equal within tolerance
+ */
+export declare function floatEquals(a: number, b: number, epsilon?: number): boolean;
+/**
+ * Checks if a number is close to zero within epsilon tolerance
+ * @param value The number to check
+ * @param epsilon Tolerance value (default: DEFAULT_EPSILON)
+ * @returns True if number is close to zero
+ */
+export declare function isNearZero(value: number, epsilon?: number): boolean;
+/**
+ * Rounds a degree value to a reasonable precision (4 decimal places)
+ * This prevents accumulation of floating-point errors in calculations
+ * @param degrees The degree value to round
+ * @returns Rounded degree value
+ */
+export declare function roundDegrees(degrees: number): number;
+/**
+ * Compares two degree values with appropriate epsilon for astrological calculations
+ * @param deg1 First degree value
+ * @param deg2 Second degree value
+ * @param epsilon Tolerance in degrees (default: 0.0001°)
+ * @returns True if degrees are equal within tolerance
+ */
+export declare function degreeEquals(deg1: number, deg2: number, epsilon?: number): boolean;
+/**
+ * Checks if a planet is exactly on a house cusp within floating-point precision
+ * @param planetDegree Planet's degree position
+ * @param cuspDegree House cusp degree
+ * @param epsilon Tolerance in degrees (default: 0.001° = about 3.6 arc-seconds)
+ * @returns True if planet is on the cusp within tolerance
+ */
+export declare function isOnCusp(planetDegree: number, cuspDegree: number, epsilon?: number): boolean;
+/**
+ * Checks if an aspect is exact within floating-point precision
+ * @param actualOrb The actual orb of the aspect
+ * @param epsilon Tolerance in degrees (default: 0.1° = 6 arc-minutes)
+ * @returns True if aspect is exact within tolerance
+ */
+export declare function isExactAspect(actualOrb: number, epsilon?: number): boolean;

package/dist/utils/precision.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Floating point precision utilities for astrological calculations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EPSILON = void 0;
+exports.floatEquals = floatEquals;
+exports.isNearZero = isNearZero;
+exports.roundDegrees = roundDegrees;
+exports.degreeEquals = degreeEquals;
+exports.isOnCusp = isOnCusp;
+exports.isExactAspect = isExactAspect;
+// Default epsilon for floating-point comparisons (about 0.0036 arc-minutes)
+exports.DEFAULT_EPSILON = 1e-4;
+/**
+ * Compares two floating-point numbers with epsilon tolerance
+ * @param a First number
+ * @param b Second number
+ * @param epsilon Tolerance value (default: DEFAULT_EPSILON)
+ * @returns True if numbers are equal within tolerance
+ */
+function floatEquals(a, b, epsilon = exports.DEFAULT_EPSILON) {
+    return Math.abs(a - b) < epsilon;
+}
+/**
+ * Checks if a number is close to zero within epsilon tolerance
+ * @param value The number to check
+ * @param epsilon Tolerance value (default: DEFAULT_EPSILON)
+ * @returns True if number is close to zero
+ */
+function isNearZero(value, epsilon = exports.DEFAULT_EPSILON) {
+    return Math.abs(value) < epsilon;
+}
+/**
+ * Rounds a degree value to a reasonable precision (4 decimal places)
+ * This prevents accumulation of floating-point errors in calculations
+ * @param degrees The degree value to round
+ * @returns Rounded degree value
+ */
+function roundDegrees(degrees) {
+    return Math.round(degrees * 10000) / 10000;
+}
+/**
+ * Compares two degree values with appropriate epsilon for astrological calculations
+ * @param deg1 First degree value
+ * @param deg2 Second degree value
+ * @param epsilon Tolerance in degrees (default: 0.0001°)
+ * @returns True if degrees are equal within tolerance
+ */
+function degreeEquals(deg1, deg2, epsilon = exports.DEFAULT_EPSILON) {
+    return floatEquals(deg1, deg2, epsilon);
+}
+/**
+ * Checks if a planet is exactly on a house cusp within floating-point precision
+ * @param planetDegree Planet's degree position
+ * @param cuspDegree House cusp degree
+ * @param epsilon Tolerance in degrees (default: 0.001° = about 3.6 arc-seconds)
+ * @returns True if planet is on the cusp within tolerance
+ */
+function isOnCusp(planetDegree, cuspDegree, epsilon = 0.001) {
+    return degreeEquals(planetDegree, cuspDegree, epsilon);
+}
+/**
+ * Checks if an aspect is exact within floating-point precision
+ * @param actualOrb The actual orb of the aspect
+ * @param epsilon Tolerance in degrees (default: 0.1° = 6 arc-minutes)
+ * @returns True if aspect is exact within tolerance
+ */
+function isExactAspect(actualOrb, epsilon = 0.1) {
+    return isNearZero(actualOrb, epsilon);
+}

package/dist/utils/validation.d.ts

@@ -0,0 +1,37 @@
+import { ChartData, Point, MultiChartData } from '../types';
+/**
+ * Validates a Point object
+ * @param point The point to validate
+ * @returns Error message if invalid, null if valid
+ */
+export declare function validatePoint(point: Point): string | null;
+/**
+ * Validates an array of Points
+ * @param points The points array to validate
+ * @returns Error message if invalid, null if valid
+ */
+export declare function validatePoints(points: Point[]): string | null;
+/**
+ * Validates house cusps array
+ * @param houseCusps The house cusps to validate
+ * @returns Error message if invalid, null if valid
+ */
+export declare function validateHouseCusps(houseCusps: number[] | undefined): string | null;
+/**
+ * Validates a ChartData object
+ * @param chartData The chart data to validate
+ * @returns Error message if invalid, null if valid
+ */
+export declare function validateChartData(chartData: ChartData): string | null;
+/**
+ * Validates MultiChartData
+ * @param multiChartData The multi-chart data to validate
+ * @returns Error message if invalid, null if valid
+ */
+export declare function validateMultiChartData(multiChartData: MultiChartData): string | null;
+/**
+ * Validates chart data (single or multi-chart)
+ * @param data The data to validate
+ * @returns Error message if invalid, null if valid
+ */
+export declare function validateInputData(data: ChartData | MultiChartData): string | null;

package/dist/utils/validation.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePoint = validatePoint;
+exports.validatePoints = validatePoints;
+exports.validateHouseCusps = validateHouseCusps;
+exports.validateChartData = validateChartData;
+exports.validateMultiChartData = validateMultiChartData;
+exports.validateInputData = validateInputData;
+/**
+ * Validates a Point object
+ * @param point The point to validate
+ * @returns Error message if invalid, null if valid
+ */
+function validatePoint(point) {
+    if (!point || typeof point !== 'object') {
+        return 'Point must be an object';
+    }
+    if (typeof point.name !== 'string' || point.name.trim() === '') {
+        return 'Point name must be a non-empty string';
+    }
+    if (typeof point.degree !== 'number' || !isFinite(point.degree)) {
+        return `Point ${point.name} has invalid degree value: ${point.degree}`;
+    }
+    if (point.speed !== undefined &&
+        (typeof point.speed !== 'number' || !isFinite(point.speed))) {
+        return `Point ${point.name} has invalid speed value: ${point.speed}`;
+    }
+    return null;
+}
+/**
+ * Validates an array of Points
+ * @param points The points array to validate
+ * @returns Error message if invalid, null if valid
+ */
+function validatePoints(points) {
+    if (!Array.isArray(points)) {
+        return 'Points must be an array';
+    }
+    for (let i = 0; i < points.length; i++) {
+        const error = validatePoint(points[i]);
+        if (error) {
+            return `Point at index ${i}: ${error}`;
+        }
+    }
+    // Check for duplicate point names
+    const names = points.map((p) => p.name);
+    const duplicates = names.filter((name, index) => names.indexOf(name) !== index);
+    if (duplicates.length > 0) {
+        return `Duplicate point names found: ${duplicates.join(', ')}`;
+    }
+    return null;
+}
+/**
+ * Validates house cusps array
+ * @param houseCusps The house cusps to validate
+ * @returns Error message if invalid, null if valid
+ */
+function validateHouseCusps(houseCusps) {
+    if (houseCusps === undefined) {
+        return null; // Optional field
+    }
+    if (!Array.isArray(houseCusps)) {
+        return 'House cusps must be an array';
+    }
+    if (houseCusps.length !== 12) {
+        return `House cusps must contain exactly 12 values, got ${houseCusps.length}`;
+    }
+    for (let i = 0; i < houseCusps.length; i++) {
+        if (typeof houseCusps[i] !== 'number' || !isFinite(houseCusps[i])) {
+            return `House cusp ${i + 1} has invalid value: ${houseCusps[i]}`;
+        }
+    }
+    return null;
+}
+/**
+ * Validates a ChartData object
+ * @param chartData The chart data to validate
+ * @returns Error message if invalid, null if valid
+ */
+function validateChartData(chartData) {
+    if (!chartData || typeof chartData !== 'object') {
+        return 'Chart data must be an object';
+    }
+    if (typeof chartData.name !== 'string' || chartData.name.trim() === '') {
+        return 'Chart name must be a non-empty string';
+    }
+    const pointsError = validatePoints(chartData.planets);
+    if (pointsError) {
+        return `Planets validation failed: ${pointsError}`;
+    }
+    if (chartData.ascendant !== undefined) {
+        if (typeof chartData.ascendant !== 'number' ||
+            !isFinite(chartData.ascendant)) {
+            return `Ascendant has invalid value: ${chartData.ascendant}`;
+        }
+    }
+    if (chartData.midheaven !== undefined) {
+        if (typeof chartData.midheaven !== 'number' ||
+            !isFinite(chartData.midheaven)) {
+            return `Midheaven has invalid value: ${chartData.midheaven}`;
+        }
+    }
+    const houseCuspsError = validateHouseCusps(chartData.houseCusps);
+    if (houseCuspsError) {
+        return `House cusps validation failed: ${houseCuspsError}`;
+    }
+    if (chartData.points !== undefined) {
+        const pointsError = validatePoints(chartData.points);
+        if (pointsError) {
+            return `Additional points validation failed: ${pointsError}`;
+        }
+    }
+    if (chartData.timestamp !== undefined) {
+        if (!(chartData.timestamp instanceof Date) ||
+            isNaN(chartData.timestamp.getTime())) {
+            return 'Timestamp must be a valid Date object';
+        }
+    }
+    if (chartData.location !== undefined) {
+        if (typeof chartData.location !== 'string') {
+            return 'Location must be a string';
+        }
+    }
+    if (chartData.chartType !== undefined) {
+        const validTypes = ['natal', 'event', 'transit'];
+        if (!validTypes.includes(chartData.chartType)) {
+            return `Chart type must be one of: ${validTypes.join(', ')}`;
+        }
+    }
+    return null;
+}
+/**
+ * Validates MultiChartData
+ * @param multiChartData The multi-chart data to validate
+ * @returns Error message if invalid, null if valid
+ */
+function validateMultiChartData(multiChartData) {
+    if (!Array.isArray(multiChartData)) {
+        return 'Multi-chart data must be an array';
+    }
+    if (multiChartData.length === 0) {
+        return 'Multi-chart data must contain at least one chart';
+    }
+    if (multiChartData.length > 10) {
+        return 'Multi-chart data cannot contain more than 10 charts';
+    }
+    for (let i = 0; i < multiChartData.length; i++) {
+        const error = validateChartData(multiChartData[i]);
+        if (error) {
+            return `Chart at index ${i} (${multiChartData[i]?.name || 'unnamed'}): ${error}`;
+        }
+    }
+    // Check for duplicate chart names
+    const names = multiChartData.map((chart) => chart.name);
+    const duplicates = names.filter((name, index) => names.indexOf(name) !== index);
+    if (duplicates.length > 0) {
+        return `Duplicate chart names found: ${duplicates.join(', ')}`;
+    }
+    // Validate transit charts
+    const transitCharts = multiChartData.filter((chart) => chart.chartType === 'transit');
+    if (transitCharts.length > 1) {
+        return 'Cannot have more than one transit chart';
+    }
+    return null;
+}
+/**
+ * Validates chart data (single or multi-chart)
+ * @param data The data to validate
+ * @returns Error message if invalid, null if valid
+ */
+function validateInputData(data) {
+    if (!data) {
+        return 'Data is required';
+    }
+    if (Array.isArray(data)) {
+        return validateMultiChartData(data);
+    }
+    else {
+        return validateChartData(data);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chart2txt",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Convert astrological chart data to human-readable text",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,6 +12,7 @@
     "test": "jest",
     "test:config": "ts-node test-configurations.ts",
     "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
     "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\""
   },
   "keywords": [