Practical Recipes

These recipes focus on product features.

Not theory.

Recipe: “profile” from name + birth date

Use this when you want a compact “esoteric profile” card.

import { calculateGematria } from 'kaabalah/gematria';
import { calculateKaabalisticLifePath } from 'kaabalah/numerology';

export function buildProfile(input: { name: string; birthDate: Date }) {
  const name = input.name.trim().toUpperCase();

  const gematria = calculateGematria(name);
  const lifePath = calculateKaabalisticLifePath(input.birthDate);

  return {
    name,
    lifePath: {
      reduced: lifePath.lifePath.reducedValue,
      synthesis: lifePath.syntheses.finalSynthesis,
    },
    gematria: {
      total: gematria.synthesis.originalSum,
      vowels: gematria.vowels.originalSum,
      consonants: gematria.consonants.originalSum,
    },
  };
}

What to show in UI:

• Life path reduced as the headline.
• Name gematria total as a secondary badge.
• A “How it’s computed” drawer using reduction steps.

Recipe: “daily numerology” (personal cycles)

Use this when you want a daily / monthly widget.

import { calculatePersonalCycles } from 'kaabalah/numerology';

const cycles = calculatePersonalCycles(
  new Date('1990-06-15'), // birth date
  new Date(),             // today
  'John',                 // first name (used for soul number)
);

console.log(cycles.personalYear.reducedValue);
console.log(cycles.currentPersonalMonth);

Practical tip:

• Cache results per day.
• Recompute at midnight in the user’s local time zone.

Recipe: birth chart (timezone-safe)

Use this when you have local birth time + place.

import { getBirthChart, HouseSystem } from 'kaabalah/astrology';

const chart = await getBirthChart({
  // Use LocalDateTimeParts to avoid browser-local-time ambiguity
  date: { year: 1990, month: 6, day: 15, hour: 12, minute: 30 },
  latitude: 40.7128,
  longitude: -74.0060,
  houseSystem: HouseSystem.PLACIDUS,
  timeZoneSettings: { timeZone: 'America/New_York' },
});

console.log(chart.planets.sun.zodiacPosition.sign);
console.log(chart.houses.ascendant.sign);
console.log(chart.sect); // "diurnal" | "nocturnal"

Caution

Astrology calculations rely on Swiss Ephemeris.

For browser usage, you’ll need the WebAssembly setup.

Recipe: draw tarot cards

Use this when you want a quick “3 cards” feature.

import { ARKANNUS, shuffleTarotDeck } from 'kaabalah/tarot';

const shuffled = await shuffleTarotDeck(ARKANNUS, /* inverted */ true);
const spread = shuffled.slice(0, 3);

for (const card of spread) {
  console.log(card.tarotCard, card.meaning);
}

Practical tip:

• Store the drawn card IDs in your DB.
• Don’t reshuffle on every rerender.

Recipe: build correspondences with the Tree of Life

Use this when you want “click a tarot card → show linked planet/element/etc.”

import { createTree, id, KaabalahTypes, TarotTypes } from 'kaabalah/core';

const tree = createTree({
  system: 'kaabalah',
  parts: ['westernAstrology', 'tarot'],
});

// Walk from The Magician to its Hebrew letter and element (depth 2)
const magicianId = id(TarotTypes.TAROT_ARK_ANNU, 'The Magician');
const related = tree.walk(magicianId, 2);

console.log(related.map((n) => n.id));

Practical tip:

• Use tree.walk(nodeId, depth, filterType) to traverse the graph.
• Serialize only what you need — the full tree can be large.

Recipe: semantic search for tarot cards

Use this when you want to match free-form user text to a tarot card.

import { listTarotThemeProfiles, tokenizeOccultThemeText } from 'kaabalah/semantic';

const profiles = listTarotThemeProfiles();

function findCards(query: string) {
  const queryTokens = new Set(tokenizeOccultThemeText(query));

  return profiles
    .map((profile) => {
      const overlap = profile.tokens.filter((t) => queryTokens.has(t)).length;
      return { card: profile.primaryLabel, score: overlap };
    })
    .filter((r) => r.score > 0)
    .sort((a, b) => b.score - a.score);
}

console.log(findCards('transformation hidden occult'));

Recipe: generate a Tree of Life SVG

Use this when you want to render or export the Tree of Life.

import { generateTreeSvg } from 'kaabalah/visual';
import { writeFileSync } from 'node:fs';

const svg = generateTreeSvg({
  palette: 'color',
  system: 'kaabalah',
});

writeFileSync('tree-of-life.svg', svg);

Practical tip:

• Pass palette: 'monochrome' for print or dark-mode use.
• Use getTreeLayout from kaabalah/visual if you need the raw coordinate data for a custom renderer.