kaabalah 6.3.0 → 6.4.1

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.
package/README.md CHANGED
@@ -1,23 +1,14 @@
1
1
  # Kaabalah
2
2
 
3
- A comprehensive TypeScript library for numerology, astrology, kaabalah, and tarot calculations and interpretations.
3
+ A comprehensive TypeScript library for numerology, astrology, kaabalah, gematria, tarot, and Ifa divination.
4
4
 
5
5
  <p align="center">
6
6
  <img src="./examples/tree-of-life-readme.svg" alt="Color Tree of Life rendered from kaabalah/visual" width="420" />
7
7
  </p>
8
8
 
9
- ## Docs
9
+ ## Documentation
10
10
 
11
- Complete documentation here [https://docs.kaabalah.com/](https://docs.kaabalah.com/)
12
-
13
- ## Features
14
-
15
- - **Tree of Life**: A modular and performant tree of life system to help you build correspondences across different systems
16
- - **Numerology**: Calculate life path numbers and other numerological values
17
- - **Astrology**: Generate birth charts and planetary positions using Swiss Ephemeris
18
- - **Gematria**: Gematria (text numerology) calculations
19
- - **Tarot**: Card meanings, spreads, and interpretations
20
- - **Semantic profiles**: Canonical house and tarot theme metadata for deterministic matching
11
+ Full API reference, guides, and examples: **[docs.kaabalah.com](https://docs.kaabalah.com/)**
21
12
 
22
13
  ## Installation
23
14
 
@@ -25,360 +16,66 @@ Complete documentation here [https://docs.kaabalah.com/](https://docs.kaabalah.c
25
16
  npm install kaabalah
26
17
  ```
27
18
 
28
- Node.js 18.18+ is required for the bundled CLI and runtime helpers.
29
-
30
- ## Support us on Ko-Fi
31
-
32
- If you find this package useful, you can support it on Ko-Fi too (or just star the repo):
33
-
34
- [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/matmoura19)
35
-
36
- ## Usage Examples
19
+ Node.js 18.18+ required.
37
20
 
38
- ### Core Library
21
+ ## Modules
39
22
 
40
- ```typescript
41
- import { createTree } from 'kaabalah/core';
42
-
43
- const tree = createTree({
44
- system: 'kaabalah',
45
- parts: ['westernAstrology', 'tarot'],
46
- });
23
+ All modules are tree-shakable and can be imported independently:
47
24
 
48
- const gematriaResult = calculateGematria('kaabalah', tree);
25
+ | Module | Import | Description |
26
+ |--------|--------|-------------|
27
+ | Core | `kaabalah/core` | Tree of Life graph with cross-system correspondences |
28
+ | Numerology | `kaabalah/numerology` | Life path, cycles, challenges, personal year |
29
+ | Astrology | `kaabalah/astrology` | Birth charts, synastry, composite, transits, solar returns, profections, firdaria, astrocartography, dignity, decans, dodecatemoria |
30
+ | Gematria | `kaabalah/gematria` | Hebrew letter numerology |
31
+ | Tarot | `kaabalah/tarot` | 78-card deck with profiles, archetypes, correspondences, multi-deck images, spread engine |
32
+ | Ifa | `kaabalah/ifa` | Odu divination |
33
+ | Semantic | `kaabalah/semantic` | Theme profiles, kaabalistic overlay correspondences, symbol metadata |
34
+ | Visual | `kaabalah/visual` | Tree of Life SVG generation and layout data |
49
35
 
50
- console.log(gematriaResult);
51
- ```
52
-
53
- ### Direct Module Imports (Tree-Shakable)
36
+ ## Quick Example
54
37
 
55
38
  ```typescript
56
- // Only import what you need
57
- import { calculateLifePath } from 'kaabalah/numerology';
39
+ import { createTree, id, KaabalahTypes } from 'kaabalah/core';
58
40
  import { getBirthChart } from 'kaabalah/astrology';
59
- import { calculateGematria } from 'kaabalah/kaabalah';
60
- import { getHouseThemeProfile } from 'kaabalah/semantic';
61
- import { getRandomSpread } from 'kaabalah/tarot';
62
-
63
- // Calculate life path number
64
- const lifePath = calculateLifePath(new Date('1990-01-15'));
65
-
66
- // Generate a birth chart (with Swiss Ephemeris)
67
- const birthChart = getBirthChart({
68
- date: new Date('1990-01-15T12:30:00Z'),
69
- latitude: 40.7128,
70
- longitude: -74.0060,
71
- timezone: -5
72
- });
73
-
74
- // Calculate Hebrew gematria
75
- const gematriaValue = calculateGematria('kaabalah');
76
- const fourthHouse = getHouseThemeProfile(4);
77
-
78
- // Get a tarot spread
79
- const spread = getRandomSpread(3, true);
80
- ```
81
-
82
- ### Canonical Tarot Image Resolution
83
-
84
- ```typescript
85
- import { id, KaabalahTypes } from "kaabalah/core";
86
- import {
87
- getTarotArchetype,
88
- getTarotCardByNumber,
89
- getTarotCardNumber,
90
- getTarotCorrespondenceProfile,
91
- getTarotCardProfile,
92
- getTarotRepresentation,
93
- listTarotTrees,
94
- resolveTarotImageUrl
95
- } from "kaabalah/tarot";
96
-
97
- const archetype = getTarotArchetype({
98
- pathId: id(KaabalahTypes.PATH, 2)
99
- });
100
-
101
- const riderWaite = getTarotRepresentation({ pathSlug: "beth" }, "rider-waite");
102
- const queenOfCups = getTarotRepresentation(
103
- { tarotCardName: "Queen of Cups" },
104
- "rider-waite"
105
- );
106
- const tenOfSwords = getTarotRepresentation(
107
- { tarotCardNumber: 55 },
108
- "mythic"
109
- );
110
- const aceOfPentacles = getTarotCardProfile({
111
- tarotCardName: "Ace of Pentacles"
112
- });
113
- const aceOfPentaclesNumber = getTarotCardNumber({
114
- tarotCardName: "Ace of Pentacles"
115
- });
116
- const kingOfSwords = getTarotCardByNumber(51);
117
- const tarotTrees = listTarotTrees();
118
- const papusImageUrl = resolveTarotImageUrl(
119
- { tarotCardFilename: "02_the_high_priestess" },
120
- "papus_pt"
121
- );
122
- const aceOfWandsUrl = resolveTarotImageUrl(
123
- { tarotCardFilename: "ace_wands" },
124
- "papus_pt"
125
- );
126
-
127
- // Persist the canonical archetype ID (for example `path:2`), not the image URL.
128
- ```
129
-
130
- `getTarotArchetype()` remains major-only. The image helpers (`getTarotRepresentation()`, `getTarotRepresentations()`, and `resolveTarotImageUrl()`) support all 78 cards and own the canonical asset rules:
131
-
132
- - majors: `major/<filename>.jpg`
133
- - minors: `minor/<suit>/<filename>.jpg`
134
- - courts: `daat+royalship/<suit>/<filename>.jpg`
135
-
136
- Downstream apps should consume the returned `imageUrl` (or `assetPath`) from the library instead of reconstructing S3 paths locally.
137
-
138
- Tarot numbering is tree-scoped. In the current library release the canonical default tree is `kaabalah`, and `getTarotCardProfile()` resolves its `tarotCardNumber` from the direct `tarotArkAnnu ↔ number` correspondence in that tree. Use `getTarotCardNumber()` / `getTarotCardByNumber()` for forward and reverse numbering lookups, and treat raw `ARKANNUS` entries as compatibility data rather than the source of truth.
139
-
140
- For display-facing correspondences, use `getTarotCorrespondenceProfile()` instead of rebuilding card bundles in the app:
141
-
142
- ```typescript
143
- const pageOfWands = getTarotCorrespondenceProfile({
144
- tarotCardName: "Page of Wands"
145
- });
146
- // {
147
- // kind: "court",
148
- // courtRank: "page",
149
- // correspondences: {
150
- // element: { id: "westernElement:Fire", label: "Fire" }
151
- // }
152
- // }
153
-
154
- const magician = getTarotCorrespondenceProfile({
155
- tarotCardName: "The Magician"
156
- });
157
- // includes typed astrology correspondences plus path metadata
158
- // { pathId, pathNumber, pathSlug, hebrewLetter, fromSphere, toSphere, meaning }
159
- ```
160
-
161
- Downstream apps no longer need to parse card-name prefixes like `Page of ...` to determine court rank, or rebuild the same major/court/minor correspondence collapsing logic from raw tree traversals.
162
-
163
- Observable kaabalah-default renumbering:
164
-
165
- - `Ten of Swords` is `55` and `Ace of Swords` is `64`
166
- - `Ten of Pentacles` is `69` and `Ace of Pentacles` is `78`
167
- - court/minor suit blocks run `King → Queen → Knight → Page → Ten → ... → Ace`
168
-
169
- ### Canonical Semantic Profiles
170
-
171
- ```typescript
172
- import {
173
- getHouseThemeProfile,
174
- getTarotThemeProfile,
175
- listHouseThemeProfiles,
176
- tokenizeOccultThemeText
177
- } from "kaabalah/semantic";
178
-
179
- const dreamTokens = tokenizeOccultThemeText(
180
- "I dreamed about family, roots, and hidden rooms."
181
- );
182
-
183
- const fourthHouse = getHouseThemeProfile(4);
184
- const tower = getTarotThemeProfile("The House of God");
185
- const houseProfiles = listHouseThemeProfiles();
186
- ```
187
-
188
- Semantic profiles are deterministic, library-owned metadata layered on top of canonical correspondences. Downstream apps should consume the profile `id`, `houseNumber` or `cardNumber`, `keywords`, `tokens`, and grouped `correspondences`, while keeping scoring, ranking, and UI presentation app-side.
189
- For houses, `primaryLabel` is the semantic life-area label and `houseLabel` preserves the structural astrological label (`Ascendant`, `Imum Coeli`, `Descendant`, `Medium Coeli`, etc.).
190
-
191
- ### Canonical Tree SVG Rendering
192
-
193
- ```typescript
194
- import { generateTreeSvg, getTreeLayout } from "kaabalah/visual";
195
-
196
- const svg = generateTreeSvg({
197
- background: "transparent",
198
- palette: "monochrome",
199
- daathLayer: "back",
200
- });
201
-
202
- const layout = getTreeLayout();
203
- const tiphareth = layout.percentages.spheres["sphere:Tiphareth"];
204
- const path15 = layout.percentages.paths["path:15"];
205
- ```
206
-
207
- `generateTreeSvg()` renders the structural tree only: paths and spheres, with no astrology, numerology, gematria, or app-specific overlays. Use it when an app needs a reusable base SVG, then place badges or glyphs using `getTreeLayout()` rather than reimplementing the coordinate math.
208
-
209
- Contract notes:
210
-
211
- - the exported `percentages` map is the canonical frontend grid shared with the existing app tree views
212
- - `viewBoxUnits` exposes the same positions in the default `286 x 561` SVG coordinate space
213
- - `palette: "color"` preserves the full-color Melkitzedeki rendering, including the special Kether, Chokhmah, Daath, and Malkuth sphere treatments
214
- - `palette: "monochrome"` simplifies the tree to plain-circle spheres with a light body and dark outline, so it still reads as a luminous tree on transparent or dark backgrounds
215
- - `daathLayer: "back"` places the Daath sphere behind the paths while still emitting a transparent top hit area for inline SVG interaction
216
-
217
- ### Canonical Tarot Spreads
41
+ import { calculateKaabalisticLifePath } from 'kaabalah/numerology';
42
+ import { getTarotCorrespondenceProfile } from 'kaabalah/tarot';
43
+ import { generateTreeSvg } from 'kaabalah/visual';
218
44
 
219
- ```typescript
220
- import {
221
- drawTarotSpread,
222
- getTarotSpread,
223
- listTarotSpreads,
224
- validateTarotSpreadSelection
225
- } from "kaabalah/tarot";
226
-
227
- const spreads = listTarotSpreads();
228
- const treeOfLife = getTarotSpread("tree-of-life-reading");
45
+ const tree = createTree({ system: 'kaabalah', parts: ['westernAstrology', 'tarot'] });
46
+ const correspondences = tree.getCorrespondences(id(KaabalahTypes.SPHERE, 'Tiphareth'), { depth: 2 });
229
47
 
230
- const drawn = drawTarotSpread({
231
- spreadId: "event-reading",
232
- context: { inquirerGender: "man" },
233
- includeInverted: true
48
+ const chart = await getBirthChart({
49
+ date: { year: 1990, month: 6, day: 15, hour: 14, minute: 30 },
50
+ latitude: 48.856, longitude: 2.352,
234
51
  });
235
52
 
236
- const validation = validateTarotSpreadSelection({
237
- spreadId: drawn.spread.spreadId,
238
- context: drawn.context,
239
- cards: drawn.cards.map((card) => ({
240
- slotKey: card.slotKey,
241
- cardNumber: card.cardNumber,
242
- isInverted: card.isInverted
243
- }))
244
- });
53
+ const lifePath = calculateKaabalisticLifePath(new Date('1990-06-15'));
54
+ const magician = getTarotCorrespondenceProfile({ tarotCardName: 'The Magician' });
55
+ const svg = generateTreeSvg({ background: 'transparent', palette: 'monochrome' });
245
56
  ```
246
57
 
247
- Downstream apps should consume `spreadId`, `slotKey`, and the slot constraint metadata from the library instead of hardcoding spread semantics. Persist the reading state as canonical spread/card data such as `spreadId`, `slotKey`, `cardNumber`, `isInverted`, and app-side notes.
248
-
249
58
  ## CLI
250
59
 
251
- Kaabalah includes a command-line interface for quick calculations without writing code.
252
-
253
60
  ```bash
254
- # Install globally
255
- npm install -g kaabalah
256
-
257
- # Or run directly with npx
258
- npx kaabalah help
61
+ npx kaabalah help # list all commands
62
+ npx kaabalah help --json # full schema introspection
63
+ npx kaabalah numerology 1990-01-15 --json --compact
64
+ npx kaabalah astrology 1990-01-15 14:30 --lat=40.71 --lon=-74 --json
65
+ npx kaabalah tree:node "tarotArkAnnu:The Magician" --depth=2 --json
259
66
  ```
260
67
 
261
- ### Commands
262
-
263
- | Command | Description |
264
- |---------|-------------|
265
- | `gematria <text>` | Calculate gematria for a word or phrase |
266
- | `gematria:reverse <number>` | Find letter combinations matching a gematria value |
267
- | `numerology <date>` | Full numerological profile for a birth date |
268
- | `numerology:lifepath <date>` | Life path number (kaabalistic method) |
269
- | `numerology:cycles <date> [name]` | Personal cycles (year, month, periods) |
270
- | `numerology:challenges <date>` | Challenges from birth date |
271
- | `numerology:fibonacci <date>` | Fibonacci cycle for current age |
272
- | `astrology <date> [time]` | Calculate birth chart with aspects using Swiss Ephemeris |
273
- | `astrology:synastry` | Cross-chart aspects between two birth charts (via `--input-json`) |
274
- | `astrology:composite` | Midpoint composite chart from two birth charts (via `--input-json`) |
275
- | `tarot [count]` | Draw tarot cards (default: 3) |
276
- | `tarot:card <number>` | Look up a specific card (1-78) |
277
- | `ifa <date>` | Calculate Odu from a date |
278
- | `tree` | Show Tree of Life structure with all nodes, data, and edges |
279
- | `tree:node <id>` | Look up a node and all its correspondences |
280
- | `tree:types` | List all node types and their counts |
68
+ 27 commands covering all modules. See the [CLI Reference](https://docs.kaabalah.com/getting-started/cli/) for the full list.
281
69
 
282
- ### Examples
283
-
284
- ```bash
285
- kaabalah gematria "Hello World"
286
- kaabalah numerology 1990-01-15
287
- kaabalah numerology:cycles 1990-01-15 John
288
- kaabalah tarot 5 --inverted
289
- kaabalah tarot:card 7
290
- kaabalah gematria:reverse 22
291
- kaabalah ifa 1990-01-15
292
- kaabalah astrology 1990-01-15 14:30 --lat=40.7128 --lon=-74.006
293
- kaabalah astrology 1990-01-15 14:30 --location="New York, USA"
294
-
295
- # Synastry (cross-chart aspects)
296
- kaabalah astrology:synastry --input-json=- --json < synastry.json
297
-
298
- # Composite (midpoint chart)
299
- kaabalah astrology:composite --input-json=- --json < composite.json
300
-
301
- # Tree of Life correspondences
302
- kaabalah tree:node path:1 --json
303
- kaabalah tree:node "tarotArkAnnu:The Magician" --depth=2 --json
304
- kaabalah tree:node sphere:Kether --type=tarotArkAnnu --json
305
- ```
306
-
307
- ### Global Flags
308
-
309
- | Flag | Description |
310
- |------|-------------|
311
- | `--json` | JSON output (auto-enabled when stdout is not a TTY) |
312
- | `--no-json` | Force human-readable output even when piped |
313
- | `--compact` | Minified JSON (no indentation) |
314
- | `--fields=a.b,c.d` | Filter JSON output to specified dot-paths |
315
- | `--input-json=-` | Read a JSON object from stdin |
316
- | `--debug` | Emit debug logs to stderr (same effect as `DEBUG=kaabalah:*`) |
317
- | `--trace` | Print stack traces for unexpected fatal errors in human-readable mode |
318
-
319
- ### Schema Introspection
320
-
321
- ```bash
322
- # Full schema of all commands
323
- kaabalah help --json
324
-
325
- # Schema for a specific command
326
- kaabalah help astrology --json
327
- ```
70
+ ## Support
328
71
 
329
- ### Debugging
330
-
331
- ```bash
332
- # Emit parser/config/astrology debug logs to stderr
333
- DEBUG=kaabalah:* kaabalah help --json
334
-
335
- # Same as above, but from the CLI flag
336
- kaabalah astrology 1990-01-15 14:30 --lat=40.7128 --lon=-74.006 --debug
337
-
338
- # Add --trace while reproducing an unexpected fatal error locally
339
- kaabalah <command> --trace --no-json
340
- ```
341
-
342
- ## Development
343
-
344
- This project uses TypeScript and WebAssembly for the Swiss Ephemeris calculations.
345
-
346
- ### Building the Project
347
-
348
- ```bash
349
- npm run build
350
- ```
351
-
352
- ### Development Mode
353
-
354
- ```bash
355
- npm run dev
356
- ```
357
-
358
- ## Swiss Ephemeris Integration
359
-
360
- The astrological calculations use the Swiss Ephemeris library, compiled to WebAssembly for use in both Node.js and browser environments.
361
-
362
- For Node apps that need stable runtime asset paths, use the exported helper instead of probing `node_modules/kaabalah` manually:
363
-
364
- ```typescript
365
- import { getSwissEph, resolveSwissEphRuntimeAssets } from "kaabalah/astrology";
366
-
367
- const assets = resolveSwissEphRuntimeAssets({
368
- wasmPathCandidates: ["./vendor/kaabalah/swisseph.node.wasm"],
369
- ephePathCandidates: ["./vendor/kaabalah/ephe"]
370
- });
371
-
372
- await getSwissEph(assets);
373
- ```
374
-
375
- If no app-specific candidates are provided, the helper falls back to the package-bundled Node assets. In browser environments it stays filesystem-free and returns the bundled browser defaults.
72
+ [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/matmoura19)
376
73
 
377
74
  ## License
378
75
 
379
- This project is licensed under the AGPL-3.0 license. See the LICENSE file for details.
76
+ AGPL-3.0 — see [LICENSE](LICENSE).
380
77
 
381
78
  ## Acknowledgments
382
79
 
383
- - [Swiss Ephemeris](https://www.astro.com/swisseph/) for providing the astronomical calculation library
384
- - [Astro.com](https://www.astro.com/) for the Swiss Ephemeris data
80
+ - [Swiss Ephemeris](https://www.astro.com/swisseph/) for astronomical calculations
81
+ - [Astro.com](https://www.astro.com/) for ephemeris data