{"id":28610049,"url":"https://github.com/0xStarcat/CircularNatalHoroscopeJS","last_synced_at":"2025-06-11T22:32:53.315Z","repository":{"id":41483495,"uuid":"207114149","full_name":"0xStarcat/CircularNatalHoroscopeJS","owner":"0xStarcat","description":"An ES6 library for many astrological chart calculations.","archived":false,"fork":false,"pushed_at":"2021-07-18T18:03:18.000Z","size":2661,"stargazers_count":306,"open_issues_count":20,"forks_count":91,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-05-31T14:26:58.229Z","etag":null,"topics":["astrological-calculations","astrology","chart","circular-charts","equal-house","horoscope","house-systems","natal-chart","zodiac"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xStarcat.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}},"created_at":"2019-09-08T13:08:47.000Z","updated_at":"2025-05-28T18:12:06.000Z","dependencies_parsed_at":"2022-09-26T16:21:22.545Z","dependency_job_id":null,"html_url":"https://github.com/0xStarcat/CircularNatalHoroscopeJS","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xStarcat%2FCircularNatalHoroscopeJS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xStarcat%2FCircularNatalHoroscopeJS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xStarcat%2FCircularNatalHoroscopeJS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xStarcat%2FCircularNatalHoroscopeJS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xStarcat","download_url":"https://codeload.github.com/0xStarcat/CircularNatalHoroscopeJS/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xStarcat%2FCircularNatalHoroscopeJS/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":257884071,"owners_count":22617531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["astrological-calculations","astrology","chart","circular-charts","equal-house","horoscope","house-systems","natal-chart","zodiac"],"created_at":"2025-06-11T22:32:15.352Z","updated_at":"2025-06-11T22:32:53.310Z","avatar_url":"https://github.com/0xStarcat.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Circular Natal Horoscope JS\n\nBy **horoscope**, we're talking about the astrological **birth charts**. **Not** horoscope readings or interpretations.\n\nI'm hoping to avoid commonly used labels like \"Western\" or \"Hellenistic\", but these are very much the circular charts you see in eur-asian based astrology traditions and not the charts in Chinese or Vedic traditions.\n\nExample Chart:\n\n![Natal Chart Example](https://raw.githubusercontent.com/0xStarcat/CircularNatalHoroscopeJS/master/public/natal-chart.svg)\n\nThe goal is to provide a library which will allow someone to:\n\n1. Enter a calendar date + time and latitude/longitude coordinates for a position on the planet Earth.\n\n2. And receive Javascript results which can be used to interface with a separate frontend library (maybe this one https://github.com/Kibo/AstroChart or a custom one) for creating the actual charts.\n\nThis package now works with typescript projects!\n\n## Current Features\n\nGiven a date/time/point of origin...\n\n1. Allows user to switch between Tropical and Sidereal zodiacs when constructing calculations.\n2. Calculates the major angles (`ascendant` and `Midheaven (MC)`) in relation to the point of origin\n3. Calculates the positions for all major bodies (`Sun`, `Moon`, `Mercury`, `Venus`, `Mars`, `Jupiter`, `Saturn`, `Uranus`, `Neptune`, `Pluto`) in relation to the point of origin\n4. Calculates the positions of the north/south Lunar Nodes and Lilith in relation to the point of origin\n5. Notes whether a planet is in retrograde at the given date/time\n6. Provides the cusps of each house in relation to the point of origin within multiple house systems.~~ (Placidus, Koch, Topocentric, Regiomontanus, Campanus, Whole Sign, and Equal House added.)\n7. Provides the cusps of each astrological sign in relation to the point of origin\n8. Provides a configurable list containing all the computed major and minor aspects of all bodies / points / angles\n9. Provides a way to extend this library with other language and deliver language-specific labels and names within the results.\n\n## Future work\n\n=\u003e Positions of the lots (Fortune, Spirit, Eros, etc)\n\n=\u003e I'm open to requests for house systems. I'm currently stopped at 6 - we have 2 \"modern\" systems (Topocentric, Koch), 3 \"medieval\" systems (Placidus, Regiomontanus, Campanus), and 2 \"ancient\" systems (Whole Sign, Equal House). My formula resource \"An Astrological House Formulary\" by Michael P. Munkasey has many more house formulas I can implement if wanted. Hopefully I covered the most popular ones.\n\n## Implementation / Use\n\n1. Get the Origin\n\n```js\nimport { Origin, Horoscope } from \"circular-natal-horoscope-js\";\n\n//////////\n// Origin\n//////////\n// This class automatically derives the local timezone from latitude/longitude coordinates\n// and calculates UTC time with respect to timezone and historical daylight savings time.\n// Only works for C.E. date (\u003e 0).\n/////////\n// * int year: value \u003e= 0 C.E.\n// * int month: (0 = january ...11 = december)\n// * int date: (1...31)\n// * int hours = local time - hours value (0...23)\n// * int minute = local time - minute value (0...59)\n// * float latitude = latitude in decimal format (-90.00...90.00)\n// * float longitude = longitude in decimal format (-180.00...180.00)\n\n// December 1st, 2020 - 430pm\nconst origin = new Origin({\n  year: 2020,\n  month: 11, // 0 = January, 11 = December!\n  date: 1,\n  hour: 16,\n  minute: 30,\n  latitude: 40.0,\n  longitude: -70.0,\n});\n```\n\n2. Configure your horoscope results\n\n```js\nimport { Origin, Horoscope } from \"circular-natal-horoscope-js\";\n\n//////////\n// Horoscope\n//////////\n// This class contains horoscope chart calculations\n/////////\n// * Origin origin: instance of the Origin class\n// * string houseSystem: one of the following: ['placidus', 'koch', 'campanus', 'whole-sign', 'equal-house', 'regiomontanus', 'topocentric'] - full list validated in self.HouseSystems\n// * string zodiac: one of the following: ['sidereal', 'tropical'] - full list validated self.ZodiacSystems\n// * array aspectPoints = an array containing all or none of the strings \"bodies\", \"points\", or \"angles\" to determine which starting points will be used in aspect generation\n// * array aspectWithPoints = an array containing all or none of the strings \"bodies\", \"points\", or \"angles\" to determine ending points will be used in aspect generation\n// * array aspectTypes = an array containing all or none of the following: \"major\", \"minor\", \"conjunction\", \"opposition\", etc to determine which aspects to calculate.\n// * object customOrbs = an object with specific keys set to override the default orbs and set your own for aspect calculation.\n// * string language = the language code (en, es, etc) which will return labels and results in a specific language, if configured.\n//\n// *NOTE: \"bodies\" = planets, \"points\" = lunar nodes / lilith, \"angles\" = ascendant / midheaven\n// *NOTE: You can also pass in individual bodies, points, or angles into aspectPoints or aspectWithPoints\n// * example: { aspectPoints: [\"sun\"], aspectWithPoints: [\"moon\"], aspectTypes: [\"major\", \"quincunx\"] }\n// * will only calculate sun to moon major or quincunx aspects if they exist\n// * All usable keys found in ./src/constant.js under BODIES, POINTS, ANGLES\n\n\nconst horoscope = new Horoscope({\n      origin: new Origin({...}),\n      houseSystem: \"whole-sign\",\n      zodiac: \"tropical\",\n      aspectPoints: ['bodies', 'points', 'angles'],\n      aspectWithPoints: ['bodies', 'points', 'angles'],\n      aspectTypes: [\"major\", \"minor\"],\n      customOrbs: {},\n      language: 'en'\n    });\n\n```\n\n2b. (optional) Set custom orb degrees for aspects. Default orbs are found in `./src/constants.js`\n\n```js\nimport { Origin, Horoscope } from \"circular-natal-horoscope-js\";\n\n\nconst customOrbs = {\n      conjunction: 8,\n      opposition: 8,\n      trine: 8,\n      square: 7,\n      sextile: 6,\n      quincunx: 5,\n      quintile: 1,\n      septile: 1,\n      \"semi-square\": 1,\n      \"semi-sextile\": 1,\n    };\n\n\nconst horoscope = new Horoscope({\n      origin: new Origin({...}),\n      houseSystem: \"whole-sign\",\n      zodiac: \"tropical\",\n      aspectPoints: ['bodies', 'points', 'angles'],\n      aspectWithPoints: ['bodies', 'points', 'angles'],\n      aspectTypes: [\"major\", \"minor\"],\n      customOrbs: customOrbs,\n      language: 'en'\n    });\n\n```\n\n3. Get your results\n\n```js\nimport { Origin, Horoscope } from \"circular-natal-horoscope-js\";\n\n\nconst horoscope = new Horoscope({...})\n\n\n// Info for all critical angles\nhoroscope.Angles = {\n  all: [...],\n  ascendant: {...},\n  midheaven: {...}\n}\n\n// The ascendant info\nhoroscope.Ascendant = {...}\n\n// Aspect results\nhoroscope.Aspects = {\n  all: [...],\n  points: {\n    // organized by point\n    ascendant: [...], // etc\n    sun: [...], // etc\n    moon: [...], // etc\n  },\n  types: {\n    // organized by type\n    conjunction: [...], // etc\n    opposition: [...] // etc\n  }\n}\n\n// Planet / Asteriod results\n// sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, chiron, sirius\nhoroscope.CelestialBodies = {\n  all: [...],\n  sun: {...}, // etc\n  moon: {...} // etc\n}\n\n// lunar results\n// northnode, southnode, lilith\nhoroscope.CelestialPoints = {\n  all: [...],\n  northnode: {...}, //etc\n}\n\n// house cusps\nhoroscope.Houses = [\n  ...12\n]\n\n// Midheaven info\n\nhoroscope.Midheaven = {\n  ...\n}\n\n// Info about what zodiac sign the sun is in at a given origin\nhoroscope.SunSign = {\n  ...\n}\n\n// Info about the zodiac cusps at the given date/time/location origin\nhoroscope.ZodiacCusps = [\n  ...12\n]\n\n```\n\n##### Interpreting ChartPositions:\n\nYou'll frequently see a `ChartPosition` class in your results for house cusps, zodiac cusps, bodies, etc. This class should give you everything you need to orient and place the cusp / body onto your circular natal chart. It provides a set of points for the object to place it along the `horizon` or the `ecliptic`.\n\nThe `horizon` is typically understood to be the inner circle on the natal chart. The `Ascendant` is commonly located at `0 degrees` along the horizon circle.\n\nThe `ecliptic` is understood to be the outer circle on the natal chart. The start of `Aries` is always at `0 degrees` along this circle.\n\n```js\nconst mercury = {\n  ...,\n  // ChartPosition for a mercury in Libra and conjunct the ascendant.\n  ChartPosition: {\n    Horizon: { // mercury is on the horizon mercury the ascendant (0 deg horizon)\n      ArcDegrees: {degrees: 0, minutes: 0, seconds: 0}\n      ArcDegreesFormatted: \"0° 0' 0''\"\n      ArcDegreesFormatted30: \"0° 0' 0''\"\n      DecimalDegrees: 0\n    },\n    Ecliptic: { // mercury is also at 180 degrees on the ecliptic, so within Libra sign.\n      ArcDegrees: {degrees: 180, minutes: 38, seconds: 2}\n      ArcDegreesFormatted: \"180° 38' 2''\"\n      ArcDegreesFormatted30: \"0° 38' 2''\"\n      DecimalDegrees: 180.634\n    }\n  }\n}\n\n```\n\n## Installation\n\nIf installing from source, clone this repo load the main file found at `dist/index.js`.\n\nThis package is also hosted on [NPM](https://www.npmjs.com/package/circular-natal-horoscope-js)\n\nInstall it with:\n\n```\nnpm i circular-natal-horoscope-js --save\n\n// or yarn\n\nyarn add circular-natal-horoscope-js\n```\n\n## Development\n\nInstall node modules\n\n```\nnpm install\n\n// or\n\nyarn install\n```\n\nThen run\n\n```\n\nyarn start:dev\n```\n\nand any changes you make should be reflected in `dist/demo.html` if you open the file in a browser.\n\nRun tests with\n\n```\nnpm test\n\n// or\n\nyarn test\n```\n\n## Building\n\nThis package uses webpack to produce a javascript bundle. If modifying this code, a new bundle can be built with the following command:\n\n```\nnpm run build\n\n// or\n\nyarn run build\n```\n\n## Demo\n\nA small HTML implementation demo is provided.\n\nTo view, build the demo files locally with:\n\n`npm run build:demo`\n\nand then open `demo/dist/demo.html` in a browser.\n\nPlease Note: The demo chart is just used as an visual example of what the library can do and isnt part of the core library. The chart uses code from this repo: [https://github.com/Kibo/AstroChart](https://github.com/Kibo/AstroChart).\n\n## Adding new languages\n\nYou can see how English and Spanish tokens are implemented in `src/utilities/language.js`. Copy the tokens for 1 language and add it to a key matching the ISO language code you want. Then, when you generate the horoscope, pass this code into the constructor:\n\n```js\nnew Horoscope({ language: \"es\" });\n```\n\nand your language will appear in the results under the `.label` keys supplied within `Sign`, `Aspect`, `Planet`, `House` objects.\n\n## Publishing / Packaging\n\nI recommend doing a github release first and then testing this package locally before publishing to npm!\nYou can test a package from a github release by adding the following to any project dependencies:\n\n```\n\"git+https://github.com/0xStarcat/CircularNatalHoroscopeJS.git#\u003ctag or commit\u003e\"\n```\n\n- update the version number in `package.json`\n- Build with `npm run build` and commit to branch\n- run `npm publish`\n\n## Sources / Special Thanks\n\n- All formula for astronomical and astrological calculations are cited in the codebase.\n- Special thanks to Mivion for their javascript implementation of Moshier's ephemeris https://github.com/mivion/ephemeris\n- and to xErik for their work converting it into a module https://github.com/xErik/ephemeris-moshier/\n- and Moshier for creating and sharing their C implementation of an ephemeris\n- \"Astronomical Algorithims\" by Jean Meeus\n- \"An Astrological House Formulary\" by Michael P. Munkasey\n- \"Dividing the Heavens\" by Leonard Williams\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xStarcat%2FCircularNatalHoroscopeJS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xStarcat%2FCircularNatalHoroscopeJS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xStarcat%2FCircularNatalHoroscopeJS/lists"}