rave-engine 1.0.0

package/src/index.js

@@ -0,0 +1,89 @@
+const { parseBirthToUtc, BirthParseError } = require('./birth/parseBirth');
+const {
+  computeEngineTest,
+  computeProfileSpheres,
+  computeActivations,
+  jdUtcFromDate,
+  findPreviousSolarLongitude,
+  signedAngleDiff,
+} = require('./calc/profile');
+const { mapLongitudeDegrees, normalizeAngleDegrees } = require('./calc/mandala');
+const { ensureEphePath, getBackend } = require('./calc/ephemeris');
+const { searchTimezones, formatOffset } = require('./timezone/search');
+const { locationForTimezone, resolveLocation } = require('./timezone/location');
+const {
+  CENTERS,
+  CENTER_LABELS,
+  GATE_CENTER,
+  CHANNELS,
+  computeBodygraph,
+} = require('./hd/bodygraph');
+const { computeAngles, computeHouses, signOf, SIGNS } = require('./hd/houses');
+const { computeChart } = require('./chart');
+
+/**
+ * High-level entry point: take human-friendly birth strings (date/time/timezone)
+ * and return the same `engine` payload that the API's /maintenance/engine_test
+ * endpoint produces, with the parsed input echoed back for traceability.
+ *
+ * For the full Gene Keys + Human Design + Astrology output, use `computeChart`.
+ *
+ * @param {{ birthdate: string, birthtime: string, timezone: string }} input
+ */
+function computeProfile(input) {
+  const birthUtc = parseBirthToUtc(input);
+  return {
+    input: {
+      birthdate: input.birthdate,
+      birthtime: input.birthtime,
+      timezone: input.timezone,
+      birth_utc: birthUtc.toISOString(),
+    },
+    engine: computeEngineTest({ birthUtc }),
+  };
+}
+
+module.exports = {
+  // Top-level convenience
+  computeProfile,
+  computeChart,
+
+  // Birth parsing
+  parseBirthToUtc,
+  BirthParseError,
+
+  // Engine internals (parity with event-horizon-api)
+  computeEngineTest,
+  computeProfileSpheres,
+  computeActivations,
+  jdUtcFromDate,
+  findPreviousSolarLongitude,
+  signedAngleDiff,
+
+  // Mandala helpers
+  mapLongitudeDegrees,
+  normalizeAngleDegrees,
+
+  // Human Design bodygraph
+  computeBodygraph,
+  CENTERS,
+  CENTER_LABELS,
+  GATE_CENTER,
+  CHANNELS,
+
+  // Extended astrology
+  computeAngles,
+  computeHouses,
+  signOf,
+  SIGNS,
+
+  // Ephemeris backend (mostly internal; exposed for power users)
+  getBackend,
+  ensureEphePath,
+
+  // Timezone autocomplete + location
+  searchTimezones,
+  formatOffset,
+  locationForTimezone,
+  resolveLocation,
+};

package/src/timezone/location.js

@@ -0,0 +1,67 @@
+// Resolve a representative geographic location (lat/lng) for an IANA timezone.
+//
+// The extended-astrology section (Ascendant / MC / houses) needs a birth
+// LOCATION, not just a timezone. To let a user "just pick the timezone they were
+// born in" and still get angles, we derive a representative location from the
+// most-populous city in that timezone (data from `city-timezones`). An explicit
+// { lat, lng } always overrides this.
+
+const cityTimezones = require('city-timezones');
+
+let _byTz = null;
+
+// Index cityMapping by IANA timezone → most-populous city, built once.
+function buildIndex() {
+  if (_byTz) return _byTz;
+  const byTz = new Map();
+  for (const c of cityTimezones.cityMapping) {
+    if (!c || !c.timezone || !Number.isFinite(c.lat) || !Number.isFinite(c.lng)) continue;
+    const existing = byTz.get(c.timezone);
+    if (!existing || (c.pop || 0) > (existing.pop || 0)) {
+      byTz.set(c.timezone, c);
+    }
+  }
+  _byTz = byTz;
+  return _byTz;
+}
+
+/**
+ * Representative location for an IANA timezone (its most-populous city).
+ * @param {string} ianaName e.g. "Asia/Bangkok"
+ * @returns {{ lat:number, lng:number, city:string, province:string|null,
+ *   country:string|null, source:'timezone-city' }|null}
+ */
+function locationForTimezone(ianaName) {
+  if (!ianaName) return null;
+  const hit = buildIndex().get(ianaName);
+  if (!hit) return null;
+  return {
+    lat: hit.lat,
+    lng: hit.lng,
+    city: hit.city || hit.city_ascii || null,
+    province: hit.province || null,
+    country: hit.country || null,
+    source: 'timezone-city',
+  };
+}
+
+/**
+ * Normalize a location input. Accepts either explicit coordinates or falls back
+ * to the timezone's representative city.
+ *
+ * @param {{ lat?:number, lng?:number, timezone?:string }} input
+ * @returns {{ lat:number, lng:number, source:string, city?, country? }|null}
+ */
+function resolveLocation(input = {}) {
+  const { lat, lng, timezone } = input;
+  if (Number.isFinite(lat) && Number.isFinite(lng)) {
+    return { lat, lng, source: 'explicit' };
+  }
+  if (timezone) {
+    const loc = locationForTimezone(timezone);
+    if (loc) return loc;
+  }
+  return null;
+}
+
+module.exports = { locationForTimezone, resolveLocation };

package/src/timezone/search.js

@@ -0,0 +1,183 @@
+const { getTimeZones } = require('@vvo/tzdb');
+const cityTimezones = require('city-timezones');
+
+// Build the tzdb index once. ~400 entries.
+//
+// We index by lowercased IANA name for O(1) merge lookups, and keep a flat list
+// for substring scanning. Each entry carries a precomputed `searchHaystack`
+// string so scoring is just a few `indexOf` calls.
+let _tzIndex = null;
+
+function buildTzIndex() {
+  if (_tzIndex) return _tzIndex;
+  const list = getTimeZones();
+  const byIana = new Map();
+  const indexed = list.map((z) => {
+    const haystackParts = [
+      z.name,
+      z.alternativeName,
+      z.abbreviation,
+      z.countryName,
+      z.countryCode,
+      ...(z.mainCities || []),
+      ...(z.group || []),
+    ].filter(Boolean);
+
+    const entry = {
+      ianaName: z.name,
+      alternativeName: z.alternativeName,
+      countryName: z.countryName,
+      countryCode: z.countryCode,
+      mainCities: z.mainCities || [],
+      mainCity: (z.mainCities && z.mainCities[0]) || null,
+      currentOffsetMinutes: z.currentTimeOffsetInMinutes,
+      rawOffsetMinutes: z.rawOffsetInMinutes,
+      abbreviation: z.abbreviation,
+      currentTimeFormat: z.currentTimeFormat,
+      _haystack: haystackParts.join('\u0001').toLowerCase(),
+      _ianaLower: z.name.toLowerCase(),
+      _altLower: (z.alternativeName || '').toLowerCase(),
+      _citiesLower: (z.mainCities || []).map((c) => c.toLowerCase()),
+    };
+
+    byIana.set(entry._ianaLower, entry);
+    return entry;
+  });
+
+  _tzIndex = { list: indexed, byIana };
+  return _tzIndex;
+}
+
+function formatOffset(minutes) {
+  if (!Number.isFinite(minutes)) return '';
+  const sign = minutes >= 0 ? '+' : '-';
+  const abs = Math.abs(minutes);
+  const hh = String(Math.floor(abs / 60)).padStart(2, '0');
+  const mm = String(abs % 60).padStart(2, '0');
+  return `${sign}${hh}:${mm}`;
+}
+
+function buildLabel(entry, hintCity) {
+  const offset = formatOffset(entry.currentOffsetMinutes);
+  const city = hintCity || entry.mainCity;
+  const cityPart = city ? ` — ${city}` : '';
+  const countryPart = entry.countryName ? ` (${entry.countryName})` : '';
+  return `${entry.ianaName} ${offset}${cityPart}${countryPart}`.trim();
+}
+
+/**
+ * Score a tzdb entry against a lowercased query.
+ * Higher is better; 0 means "no match".
+ */
+function scoreTzEntry(entry, q) {
+  if (!q) return 0;
+
+  // Strongest: exact IANA hit.
+  if (entry._ianaLower === q) return 1000;
+
+  // IANA prefix / contains.
+  if (entry._ianaLower.startsWith(q)) return 800;
+  // Match against the segment after a slash, e.g. "tokyo" → "asia/tokyo".
+  const lastSegment = entry._ianaLower.split('/').pop();
+  if (lastSegment.startsWith(q)) return 750;
+
+  // City prefix.
+  for (const c of entry._citiesLower) {
+    if (c === q) return 700;
+    if (c.startsWith(q)) return 650;
+  }
+
+  // Alternative name prefix (e.g. "central european" → "Central European Time").
+  if (entry._altLower.startsWith(q)) return 500;
+
+  // Generic contains anywhere in the haystack.
+  if (entry._haystack.includes(q)) return 200;
+
+  return 0;
+}
+
+/**
+ * Search timezones by free-text query.
+ *
+ * Combines @vvo/tzdb (rich IANA metadata + current offsets) with
+ * city-timezones (city → IANA lookup, including province/state matches like
+ * "Bali" → Asia/Makassar). Results are deduplicated by IANA name and ranked
+ * by a small scoring function.
+ *
+ * @param {string} query
+ * @param {{ limit?: number }} [options]
+ * @returns {Array<{
+ *   ianaName: string,
+ *   mainCity: string|null,
+ *   countryName: string|null,
+ *   currentOffsetMinutes: number,
+ *   abbreviation: string|null,
+ *   label: string,
+ *   score: number,
+ * }>}
+ */
+function searchTimezones(query, options = {}) {
+  const limit = Number.isFinite(options.limit) ? options.limit : 10;
+  const q = String(query || '').trim().toLowerCase();
+  if (!q) return [];
+
+  const { list, byIana } = buildTzIndex();
+
+  // 1) Score every tzdb entry directly.
+  const scored = new Map(); // ianaLower -> { entry, score, hintCity }
+  for (const entry of list) {
+    const s = scoreTzEntry(entry, q);
+    if (s > 0) {
+      scored.set(entry._ianaLower, { entry, score: s, hintCity: null });
+    }
+  }
+
+  // 2) Mine city-timezones for province/state-level hits and fold them in.
+  //    findFromCityStateProvince does case-insensitive substring matching across
+  //    city, state and province, which is what makes "bali" → Asia/Makassar work.
+  let cityHits = [];
+  try {
+    cityHits = cityTimezones.findFromCityStateProvince(q) || [];
+  } catch (_e) {
+    cityHits = [];
+  }
+
+  for (const hit of cityHits) {
+    if (!hit || !hit.timezone) continue;
+    const ianaLower = String(hit.timezone).toLowerCase();
+    const entry = byIana.get(ianaLower);
+    if (!entry) continue;
+
+    // City score: lower than direct IANA/city tzdb hits (which the loop above
+    // already caught), but better than a generic substring miss.
+    const cityScore = 600;
+
+    const existing = scored.get(ianaLower);
+    if (!existing || existing.score < cityScore) {
+      scored.set(ianaLower, { entry, score: cityScore, hintCity: hit.city });
+    } else if (!existing.hintCity && hit.city) {
+      // Keep the higher score, but enrich the label with the matched city name.
+      existing.hintCity = hit.city;
+    }
+  }
+
+  return Array.from(scored.values())
+    .sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      // Tie-break: prefer larger populations indirectly via tzdb's "main city"
+      // ordering. Falls back to alphabetical.
+      return a.entry.ianaName.localeCompare(b.entry.ianaName);
+    })
+    .slice(0, limit)
+    .map(({ entry, score, hintCity }) => ({
+      ianaName: entry.ianaName,
+      mainCity: entry.mainCity,
+      countryName: entry.countryName,
+      currentOffsetMinutes: entry.currentOffsetMinutes,
+      abbreviation: entry.abbreviation,
+      label: buildLabel(entry, hintCity),
+      score,
+    }));
+}
+
+module.exports = { searchTimezones, formatOffset };