{"id":47817998,"url":"https://github.com/h4x0r/stem-branch","last_synced_at":"2026-04-03T18:53:11.050Z","repository":{"id":341310792,"uuid":"1169659212","full_name":"h4x0r/stem-branch","owner":"h4x0r","description":"Chinese astronomical calendar, bazi (四柱八字), and divination for TypeScript. Solar terms (節氣) to sub-second precision, lunar calendar (農曆), flying stars (紫白九星), almanac flags (神煞), Six Ren (大六壬) — zero dependencies.","archived":false,"fork":false,"pushed_at":"2026-03-26T13:41:57.000Z","size":4519,"stargazers_count":2,"open_issues_count":11,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T00:54:42.469Z","etag":null,"topics":["almanac","astronomy","bazi","chinese-calendar","chinese-zodiac","divination","eclipses","five-elements","four-pillars","lunar-calendar","six-ren","solar-terms","stem-branch","vsop87"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/h4x0r.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-01T02:22:52.000Z","updated_at":"2026-03-26T16:56:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/h4x0r/stem-branch","commit_stats":null,"previous_names":["h4x0r/stembranch","h4x0r/stem-branch"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/h4x0r/stem-branch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h4x0r%2Fstem-branch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h4x0r%2Fstem-branch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h4x0r%2Fstem-branch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h4x0r%2Fstem-branch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/h4x0r","download_url":"https://codeload.github.com/h4x0r/stem-branch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h4x0r%2Fstem-branch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31370326,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["almanac","astronomy","bazi","chinese-calendar","chinese-zodiac","divination","eclipses","five-elements","four-pillars","lunar-calendar","six-ren","solar-terms","stem-branch","vsop87"],"created_at":"2026-04-03T18:53:10.283Z","updated_at":"2026-04-03T18:53:11.035Z","avatar_url":"https://github.com/h4x0r.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# stem-branch\n\nThe most accurate open-source Chinese calendar engine. Solar terms verified to **1.05 seconds mean** against JPL DE441 across 2,300 years of history. Zero dependencies. TypeScript.\n\n[![npm](https://img.shields.io/npm/v/%404n6h4x0r%2Fstem-branch)](https://www.npmjs.com/package/@4n6h4x0r/stem-branch)\n[![license](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)\n[![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)]()\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue)](https://www.typescriptlang.org/)\n\n## Accuracy\n\nEvery result is computed from first principles — full VSOP87D (2,425 terms) with a DE441-fitted correction polynomial, IAU2000B nutation, and Meeus Ch. 49 lunar algorithms — then validated against JPL's numerical ephemeris.\n\n**vs JPL DE441 (primary reference):**\n\n| Test | Range | Result |\n|------|-------|--------|\n| Solar term timing | 209–2493 CE (1,008 terms) | mean **1.05 s**, max 3.05 s |\n| Equation of Time | 2024 (366 days) | max **0.03 s** |\n| Planetary longitude | 1900–2100 (808 epochs) | **1–14″** mean |\n| Lunar phase timing | 2000–2024 (594 phases) | **3.6″** mean elongation error |\n\n**vs [sxwnl](https://github.com/sxwnl/sxwnl) (寿星万年历, the most widely-cited open-source alternative):**\n\n| Metric | stem-branch | sxwnl |\n|--------|-------------|-------|\n| Mean solar term error (vs JPL) | **1.05 s** | 2.38 s |\n| Max solar term error (vs JPL) | **3.05 s** | 7.18 s |\n| Validated range | **209–2493 CE** | 1900–2100 CE |\n| Extended computation | **10,392 terms, 0 failures** | — |\n| Timeline where equal or better | **98.9%** | 1.1% |\n\nFull methodology with 14 charts, polynomial analysis, and 7,000-year extended range data: **[Accuracy Report](https://h4x0r.github.io/stem-branch/accuracy)**\n\n## Install\n\n```bash\nnpm install @4n6h4x0r/stem-branch\n```\n\nZero production dependencies. Works in Node.js, browsers, and edge runtimes.\n\n## Quick Examples\n\n### Four Pillars (四柱八字)\n\n```typescript\nimport { computeFourPillars } from '@4n6h4x0r/stem-branch';\n\nconst pillars = computeFourPillars(new Date(2024, 1, 10, 14, 30));\n// → year: 甲辰, month: 丙寅, day: 壬午, hour: 丁未\n```\n\n### Daily Almanac (日曆總覽)\n\nOne call, everything at once — four pillars, lunar date, solar terms, zodiac, day fitness, flying stars, almanac flags, Six Ren chart, eclipses, and element analysis:\n\n```typescript\nimport { dailyAlmanac } from '@4n6h4x0r/stem-branch';\n\nconst a = dailyAlmanac(new Date(2024, 5, 15));\n// a.pillars      → year/month/day/hour stem-branch pairs\n// a.lunar        → { year: 2024, month: 5, day: 10, isLeapMonth: false }\n// a.dayFitness   → { fitness: '成', auspicious: true }\n// a.almanacFlags → [{ name: '天乙貴人', english: 'Heavenly Noble', ... }, ...]\n// a.sixRen       → { method: '賊剋', lessons: [...], ... }\n// a.flyingStars  → { year: {...}, month: {...}, day: {...}, hour: {...} }\n```\n\n### Seven Governors (七政四餘)\n\nChinese sidereal astrology — 11 celestial bodies placed in 28 lunar mansions and 12 palaces:\n\n```typescript\nimport { getSevenGovernorsChart } from '@4n6h4x0r/stem-branch';\n\nconst chart = getSevenGovernorsChart(\n  new Date('1990-01-15T00:30:00Z'),\n  { lat: 25.033, lon: 121.565 },\n);\n// chart.bodies.sun     → { siderealLon, mansion, mansionDegree, palace }\n// chart.palaces         → 12 palaces with roles relative to ascendant\n// chart.aspects         → inter-body aspects (合/沖/刑/三合)\n// chart.dignities       → per-body dignity (廟/旺/平/陷)\n```\n\n## What's Inside\n\n### Astronomy\n\n| Export | Description |\n|--------|-------------|\n| `getSolarTermsForYear(year)` | All 24 solar terms with exact UTC times |\n| `gregorianToLunar(date)` | Gregorian → lunar date conversion |\n| `getEclipsesForYear(year)` | Solar and lunar eclipses (−1999 to 3000 CE) |\n| `equationOfTime(date)` | Equation of Time in minutes |\n| [+ 14 more →](https://h4x0r.github.io/stem-branch/api/astronomy) | |\n\n### Stem-Branch System (干支)\n\n| Export | Description |\n|--------|-------------|\n| `STEMS` / `BRANCHES` | 天干地支 arrays |\n| `allSixtyStemBranch()` | All 60 valid pairs in cycle order |\n| `getElementRelation(from, to)` | Five Elements relationship (生/剋/比和) |\n| `getCycleElement(sb)` | 納音 element for a stem-branch pair |\n| [+ 12 more →](https://h4x0r.github.io/stem-branch/api/stem-branch) | |\n\n### Four Pillars \u0026 Derivations (四柱八字)\n\n| Export | Description |\n|--------|-------------|\n| `computeFourPillars(date)` | Year, month, day, and hour pillars |\n| `computeMajorLuck(date, gender)` | 大運 ten-year luck periods |\n| `getAlmanacFlags(date)` | All active 神煞 for a date |\n| `getTenRelation(dayStem, other)` | Ten Relations (十神) |\n| [+ 45 more →](https://h4x0r.github.io/stem-branch/api/four-pillars) | |\n\n### Almanac Features (曆書)\n\n| Export | Description |\n|--------|-------------|\n| `getDayFitnessForDate(date)` | 建除十二神 fitness + auspicious flag |\n| `getFlyingStars(date)` | 紫白九星 year/month/day/hour stars |\n| `getChineseZodiac(date)` | 生肖 with configurable year boundary |\n| `getPengZuTabooForDate(date)` | 彭祖百忌 daily taboos |\n| [+ 15 more →](https://h4x0r.github.io/stem-branch/api/almanac) | |\n\n### Divination Systems (三式)\n\n| Export | Description |\n|--------|-------------|\n| `computeSixRenForDate(date)` | 大六壬 full chart |\n| `computeQiMenForDate(date)` | 奇門遁甲 full chart |\n| `computeZiWei(birthData)` | 紫微斗數 full chart |\n| [+ 15 more →](https://h4x0r.github.io/stem-branch/api/divination) | |\n\n### Seven Governors (七政四餘)\n\n| Export | Description |\n|--------|-------------|\n| `getSevenGovernorsChart(date, location)` | Complete natal chart with all 11 bodies |\n| `toSiderealLongitude(lon, date)` | Tropical → sidereal conversion (3 modes) |\n| `getRahuPosition(date)` | 羅睺 Moon's ascending node |\n| `getMansionForLongitude(lon)` | Map to one of 28 lunar mansions |\n| [+ 6 more →](https://h4x0r.github.io/stem-branch/api/seven-governors) | |\n\n### Timezone \u0026 Location (時區)\n\n| Export | Description |\n|--------|-------------|\n| `localToUtc(y, m, d, h, min, tz)` | Wall clock → UTC with historical DST |\n| `wallClockToSolarTime(...)` | Full true solar time pipeline |\n| `searchCities(query)` | Search 143 cities by name or pinyin |\n| [+ 10 more →](https://h4x0r.github.io/stem-branch/api/timezone) | |\n\n## Documentation\n\n- **[Getting Started](https://h4x0r.github.io/stem-branch/getting-started)** — install, examples, and \"What's Inside\" overview\n- **[API Reference](https://h4x0r.github.io/stem-branch/api/astronomy)** — full export tables and TypeScript types\n- **[Reference Tables](https://h4x0r.github.io/stem-branch/reference/almanac-flags)** — 神煞, 建除十二神, 天德月德, 神煞方位 lookup tables\n- **[Algorithms](https://h4x0r.github.io/stem-branch/algorithms/overview)** — how solar longitude, four pillars, and lunar calendar are computed\n- **[Accuracy Report](https://h4x0r.github.io/stem-branch/accuracy)** — full validation against JPL DE441, Swiss Ephemeris, and sxwnl\n- **[Seven Governors](https://h4x0r.github.io/stem-branch/seven-governors)** — 七政四餘 computation methods and historical context\n\n## License\n\n[Apache-2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh4x0r%2Fstem-branch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fh4x0r%2Fstem-branch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh4x0r%2Fstem-branch/lists"}