astro-ascendant 0.1.0 → 0.1.2

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.
Files changed (2) hide show
  1. package/README.md +63 -115
  2. package/package.json +6 -11
package/README.md CHANGED
@@ -1,184 +1,132 @@
1
1
  # astro-ascendant
2
2
 
3
- `astro-ascendant` is an Effect-first TypeScript library for Vedic astrology calculations. It calculates sidereal Placements, D1 and divisional Charts, Vimshottari Dasha timelines, and classical Parashari Ashtakavarga.
3
+ [![npm version](https://img.shields.io/npm/v/astro-ascendant)](https://www.npmjs.com/package/astro-ascendant)
4
+ [![License](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)
4
5
 
5
- The library calculates planetary positions once for a Located Moment. Chart, Dasha, and SAV modules then share those Placements without repeating ephemeris work.
6
+ Effect-first TypeScript library for sidereal Vedic astrology calculations.
6
7
 
7
- ## Features
8
-
9
- - **Shared Placements**: sidereal longitudes, motion states, nakshatras, and pada
10
- - **Charts**: D1, 15 divisional Charts, and a configured Bhava chart from one calculation
11
- - **Methodologies**: 39 predefined ayanamsas and 13 house systems
12
- - **Vimshottari Dasha**: Mahadasha and Antardasha timelines with date queries
13
- - **Ashtakavarga**: BAV, SAV, reduced BAV, and Shodhya Pinda
14
- - **Yogas**: classical Yoga catalog with structured evidence and bounded concurrency
15
- - **Effect integration**: named effects, typed context, layers, schemas, and domain errors
16
- - **Runtime-neutral core**: use the bundled Node/Bun adapter or provide another Ephemeris adapter
8
+ `astro-ascendant` calculates planetary Placements once for a Located Moment, then derives charts, Vimshottari Dasha timelines, Ashtakavarga, Yogas, and Jaimini results from that shared calculation. It includes a Swiss Ephemeris adapter for Node.js and Bun, plus a runtime-neutral ephemeris interface for custom adapters.
17
9
 
18
10
  ## Installation
19
11
 
20
- Install the library with its Effect peer dependency. Add the Swiss Ephemeris adapter when you run calculations in Node.js or Bun.
12
+ Install the package and its Effect peer dependency:
21
13
 
22
14
  ```bash
23
- npm install astro-ascendant effect @swisseph/node
15
+ npm install astro-ascendant effect
24
16
  ```
25
17
 
26
- The package uses ES modules and ships TypeScript declarations.
18
+ The package includes the Swiss Ephemeris adapter dependency, uses ES modules, and includes TypeScript declarations.
27
19
 
28
- ## Calculate a chart
20
+ ## Quick start
29
21
 
30
- Create a Located Moment, provide the runtime layers once, and request the divisions you need. D1 is always included as the first Chart.
22
+ This example generates a D1 and D9 chart for a birth moment in Bengaluru. `SwissephLayer` supplies the ephemeris implementation, while `DefaultAstroParams` selects Lahiri ayanamsa and Whole Sign houses.
31
23
 
32
24
  ```typescript
33
- import { BunRuntime } from "@effect/platform-bun";
34
25
  import { AstroParams, Chart } from "astro-ascendant";
35
26
  import * as Swisseph from "astro-ascendant/swisseph";
36
- import { Console, DateTime, Effect, Layer } from "effect";
27
+ import { DateTime, Effect, Layer } from "effect";
37
28
 
38
- const moment = Chart.Moment.make({
39
- date: DateTime.makeUnsafe("2000-01-01T12:00:00.000Z"),
40
- });
41
29
  const input = Chart.LocatedMoment.make({
42
- moment,
30
+ moment: Chart.Moment.make({
31
+ date: DateTime.makeUnsafe("2000-01-01T12:00:00.000Z"),
32
+ }),
43
33
  latitude: 12.9716,
44
34
  longitude: 77.5946,
45
35
  });
46
36
 
47
- const program = Chart.generate(input, [9, 10]);
48
- const runtimeLayer = Layer.merge(AstroParams.DefaultAstroParams, Swisseph.SwissephLayer);
37
+ const program = Chart.generate(input, [9]);
38
+ const layers = Layer.merge(AstroParams.DefaultAstroParams, Swisseph.SwissephLayer);
39
+ const calculation = await Effect.runPromise(program.pipe(Effect.provide(layers)));
49
40
 
50
- BunRuntime.runMain(program.pipe(Effect.provide(runtimeLayer)));
41
+ console.log(calculation.charts[0]); // D1
42
+ console.log(calculation.charts[1]); // D9
51
43
  ```
52
44
 
53
- `calculation.placements` contains the shared source longitudes. `calculation.charts` contains D1, D9, and D10 in deterministic order. `calculation.bhava` contains the twelve cusp-defined houses and all eight house angles. `calculation.astroParams` records the resolved methodology used for the result.
45
+ `calculation.placements` contains the shared sidereal positions. `calculation.charts` contains D1 first, followed by the requested divisions in numeric order. `calculation.bhava` contains the cusp-defined house projection.
54
46
 
55
- ## Derive Dasha and Ashtakavarga
47
+ ## Calculations
56
48
 
57
- Pass the shared Placements to the Dasha and SAV modules. Both calculations stay in process and do not call the Ephemeris adapter again.
49
+ The package exposes named operations for each calculation surface:
50
+
51
+ - **Charts**: D1 and 15 divisional charts, plus a configured Bhava chart
52
+ - **Vimshottari Dasha**: Mahadasha and Antardasha timelines with date queries
53
+ - **Ashtakavarga**: Bhinnashtakavarga, Sarvashtakavarga, reduced BAV, and Shodhya Pinda
54
+ - **Yogas**: versioned classical Yoga catalog with structured evidence
55
+ - **Jaimini**: Chara Karakas, Rashi Drishti, Karakamsha, Arudha Pada, Upapada, and Argala
56
+ - **Methodologies**: 39 predefined ayanamsas and 13 house systems
57
+
58
+ For example, derive Dasha and Ashtakavarga from an existing chart without repeating ephemeris work:
58
59
 
59
60
  ```typescript
60
61
  import { Dasha, SAV } from "astro-ascendant";
61
62
 
62
- const derivedProgram = Effect.gen(function* () {
63
- const timeline = yield* Dasha.calculate(moment, calculation.placements);
64
- const current = yield* Dasha.at(timeline);
63
+ const derived = Effect.gen(function* () {
64
+ const timeline = yield* Dasha.calculate(input.moment, calculation.placements);
65
+ const current = yield* Dasha.at(timeline, input.moment.date);
65
66
  const ashtakavarga = yield* SAV.calculate(calculation.placements);
66
67
 
67
68
  return { timeline, current, ashtakavarga };
68
69
  });
69
70
  ```
70
71
 
71
- `Dasha.at` queries the active Mahadasha and Antardasha with half-open UTC intervals. The SAV result contains these fields:
72
-
73
- - `bhinna`: BAV tables for the 7 classical planets and Lagna
74
- - `sarva`: the 12 SAV scores, excluding Lagna BAV
75
- - `reduced`: Trikona and Ekadhipatya reduced planetary BAV tables
76
- - `shodhya_pinda`: Rashi, Graha, and total Shodhya Pinda by planet
77
- - `totals`: classical BAV checksums and the SAV total of 337
72
+ ## Configuration
78
73
 
79
- ## Evaluate Yogas
80
-
81
- Evaluate the built-in Yoga rule set against an existing Chart calculation. The module preflights the required divisions, then runs the definitions with bounded concurrency and returns structured evidence per definition.
74
+ Pass an `AstroParams` layer to select the ayanamsa and house system:
82
75
 
83
76
  ```typescript
84
- import { Yoga } from "astro-ascendant";
85
-
86
- const yogaProgram = Effect.gen(function* () {
87
- const evaluation = yield* Yoga.evaluateAll(calculation);
88
-
89
- for (const { yoga: descriptor, present } of evaluation.results) {
90
- if (present) yield* Console.log(descriptor.name);
91
- }
92
-
93
- return yield* Yoga.evaluateSelected(calculation, [
94
- Yoga.YogaId.make("gajakesari"),
95
- Yoga.YogaId.make("sunapha"),
96
- ]);
97
- });
98
- ```
99
-
100
- `Yoga.catalog` lists every definition's descriptor without running any calculation. Unknown, duplicate, or empty selections and missing Chart divisions fail through the typed error channel before definitions start. Each result carries a `YogaEvidence` tree that `Yoga.formatEvidence` renders as text.
101
-
102
- ## Configure calculation parameters
103
-
104
- `AstroParams.DefaultAstroParams` uses Lahiri ayanamsa and Whole Sign houses. Provide another layer for a different supported methodology.
105
-
106
- ```typescript
107
- const paramsLayer = AstroParams.layer({
77
+ const params = AstroParams.layer({
108
78
  ayanamsa: "Raman",
109
79
  houseSystem: "Placidus",
110
80
  });
111
81
  ```
112
82
 
113
- The Chart module produces sign-based D1 and divisional Charts, so their houses remain Whole Sign. The configured `houseSystem` changes only `calculation.bhava`; the shared Placements and sign-based Charts retain their own semantics.
114
-
115
- ### Supported ayanamsas
116
-
117
- The stable public ayanamsa set follows the predefined Swiss Ephemeris identifiers:
118
-
119
- `FaganBradley`, `Lahiri`, `DeLuce`, `Raman`, `Ushashashi`, `Krishnamurti`, `DjwhalKhul`, `Yukteshwar`, `JNBhasin`, `BabylKugler1`, `BabylKugler2`, `BabylKugler3`, `BabylHuber`, `BabylEtPSC`, `Aldebaran15Tau`, `Hipparchos`, `Sassanian`, `GalacticCenter0Sag`, `J2000`, `J1900`, `B1950`, `SuryaSiddhanta`, `SuryaSiddhantaMeanSun`, `Aryabhata`, `AryabhataMeanSun`, `SSRevati`, `SSCitra`, `TrueCitra`, `TrueRevati`, `TruePushya`, `GalacticCenterGilBrand`, `GalacticEquatorIAU1958`, `GalacticEquator`, `GalacticEquatorMidMula`, `Skydram`, `TrueMula`, `DhruvaGalCenterMulaWilhelm`, `Aryabhata522`, and `BabylBritton`.
120
-
121
- `UserDefined` is not supported because it requires custom epoch and offset parameters that are outside the public AstroParams contract.
122
-
123
- ### Supported house systems
83
+ The configured house system changes `calculation.bhava`. D1 and divisional charts remain sign-based charts with Whole Sign houses.
124
84
 
125
- The supported house systems are `Placidus`, `Koch`, `Porphyrius`, `Regiomontanus`, `Campanus`, `Equal`, `VehlowEqual`, `WholeSign`, `Meridian`, `Azimuthal`, `PolichPage`, `Alcabitus`, and `Morinus`.
126
-
127
- Some systems, including Placidus and Koch, cannot be calculated at certain polar latitudes. These cases fail through the typed Effect error channel; the adapter does not silently return a different house system.
128
-
129
- ## Supported divisions
130
-
131
- The Chart module supports these divisions:
132
-
133
- `D1`, `D2`, `D3`, `D4`, `D7`, `D9`, `D10`, `D12`, `D16`, `D20`, `D24`, `D27`, `D30`, `D40`, `D45`, and `D60`.
134
-
135
- Duplicate requests are calculated once. The returned collection always begins with D1 and orders the remaining divisions numerically.
85
+ Supported divisions are `D1`, `D2`, `D3`, `D4`, `D7`, `D9`, `D10`, `D12`, `D16`, `D20`, `D24`, `D27`, `D30`, `D40`, `D45`, and `D60`.
136
86
 
137
87
  ## Package exports
138
88
 
139
- Import namespaces from the package root or use focused entry points:
89
+ Use the package root for the main namespaces, or import a focused entry point:
90
+
91
+ | Entry point | Contents |
92
+ | ------------------------------- | ----------------------------------------------------------------------------------- |
93
+ | `astro-ascendant` | `AstroParams`, `Chart`, `Dasha`, `Ephemeris`, `SAV`, `Yoga`, and Jaimini namespaces |
94
+ | `astro-ascendant/chart` | Chart models, generation, projection, and errors |
95
+ | `astro-ascendant/dasha` | Vimshottari Dasha calculation and queries |
96
+ | `astro-ascendant/sav` | Ashtakavarga calculation and models |
97
+ | `astro-ascendant/yoga` | Yoga catalog, evaluation, and evidence formatting |
98
+ | `astro-ascendant/swisseph` | Swiss Ephemeris adapter |
99
+ | `astro-ascendant/astro-params` | Calculation parameter models and layers |
100
+ | `astro-ascendant/argala` | Jaimini Argala calculation |
101
+ | `astro-ascendant/arudha-pada` | Jaimini Arudha Pada calculation |
102
+ | `astro-ascendant/chara-karakas` | Jaimini Chara Karaka calculation |
103
+ | `astro-ascendant/karakamsha` | Jaimini Karakamsha calculation |
104
+ | `astro-ascendant/rashi-drishti` | Jaimini Rashi Drishti calculation |
105
+ | `astro-ascendant/upapada` | Jaimini Upapada calculation |
140
106
 
141
- | Import | Purpose |
142
- | ------------------------------------------ | ------------------------------------------------------------------ |
143
- | `astro-ascendant` | `AstroParams`, `Chart`, `Dasha`, `Ephemeris`, and `SAV` namespaces |
144
- | `astro-ascendant/chart` | Chart models, schemas, errors, generation, and projection |
145
- | `astro-ascendant/dasha` | Vimshottari Dasha models, calculation, and UTC lookup |
146
- | `astro-ascendant/sav` | Ashtakavarga models, errors, and calculation |
147
- | `astro-ascendant/yoga` | Yoga models, rule set, errors, evaluation, and evidence formatting |
148
- | `astro-ascendant/astro-params` | Calculation parameter models and layers |
149
- | `astro-ascendant/ephemeris` | Runtime-neutral ephemeris contract and models |
150
- | `astro-ascendant/swisseph` | Swiss Ephemeris adapter for Node.js and Bun |
151
- | `astro-ascendant/chart/divisional-mapping` | Focused divisional mapping functions |
107
+ See the [API documentation](https://ascendant-docs.vercel.app) for the complete public surface and methodology details.
152
108
 
153
- ## Examples
109
+ ## Run the examples
154
110
 
155
- The executable examples read `MOMENT_DATE`, `LATITUDE`, and `LONGITUDE` from the environment:
111
+ The repository includes interactive examples for charts, Dasha, Jaimini, Ashtakavarga, and Yogas:
156
112
 
157
113
  ```bash
158
- MOMENT_DATE=2000-01-01T12:00:00.000Z \
159
- LATITUDE=12.9716 \
160
- LONGITUDE=77.5946 \
161
- bun run examples/chart.ts
114
+ bun install
115
+ make run
162
116
  ```
163
117
 
164
- Replace `chart.ts` with `dasha.ts`, `sav.ts`, `yoga.ts`, or `jaimini.ts` to print the
165
- corresponding tables.
166
- The Jaimini example composes Chara Karakas, Rashi Drishti, Karakamsha, Arudha Pada,
167
- Upapada, and Argala through their separately named operations.
118
+ The runner accepts `MOMENT_DATE`, `LATITUDE`, and `LONGITUDE` from the environment or lets you enter the moment and location interactively.
168
119
 
169
120
  ## Development
170
121
 
171
- Install dependencies and run the complete verification suite:
122
+ Run the full local verification suite:
172
123
 
173
124
  ```bash
174
125
  bun install
175
126
  make check
176
127
  ```
177
128
 
178
- Use `make help` to list the available development commands.
179
-
180
- Run the non-gating Yoga benchmark with `bun run benchmark:yoga`; see
181
- [benchmarks/README.md](benchmarks/README.md) for methodology and recent numbers.
129
+ Use `make help` to list all available commands. Run the non-gating Yoga benchmark with `bun run benchmark:yoga`; its methodology is documented in [benchmarks/README.md](benchmarks/README.md).
182
130
 
183
131
  ## License
184
132
 
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "astro-ascendant",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
+ "homepage": "https://ascendant-docs.vercel.app",
4
5
  "license": "AGPL-3.0-or-later",
5
6
  "files": [
6
7
  "dist",
@@ -78,6 +79,9 @@
78
79
  "access": "public",
79
80
  "provenance": true
80
81
  },
82
+ "dependencies": {
83
+ "@swisseph/node": "^1.3.1"
84
+ },
81
85
  "scripts": {
82
86
  "prepare": "effect-tsgo patch --typescript --oxlint",
83
87
  "build": "tsc -p tsconfig.build.json",
@@ -92,13 +96,10 @@
92
96
  "package:check": "bun run build && tsc -p tsconfig.package.json && bun tests/package/runtime.mjs && bun pm pack --dry-run",
93
97
  "check": "bun run typecheck && bun run test && bun run lint && bun run fmt:check && bun run build"
94
98
  },
95
- "dependencies": {
96
- "@effect/platform-bun": "^4.0.0-rc.112"
97
- },
98
99
  "devDependencies": {
100
+ "@effect/platform-bun": "^4.0.0-rc.112",
99
101
  "@effect/tsgo": "0.37.0",
100
102
  "@effect/vitest": "^4.0.0-rc.112",
101
- "@swisseph/node": "^1.3.1",
102
103
  "effect": "^4.0.0-rc.112",
103
104
  "oxfmt": "^0.65.0",
104
105
  "oxlint": "1.80.0",
@@ -107,14 +108,8 @@
107
108
  "vitest": "latest"
108
109
  },
109
110
  "peerDependencies": {
110
- "@swisseph/node": "^1.3.1",
111
111
  "effect": "^4.0.0-rc.112"
112
112
  },
113
- "peerDependenciesMeta": {
114
- "@swisseph/node": {
115
- "optional": true
116
- }
117
- },
118
113
  "trustedDependencies": [
119
114
  "@swisseph/node",
120
115
  "msgpackr-extract"