{"id":28565750,"url":"https://github.com/postlight/seasons","last_synced_at":"2025-09-23T16:44:23.503Z","repository":{"id":143344617,"uuid":"610986267","full_name":"postlight/seasons","owner":"postlight","description":":moon: Calculates the astronomical season for a given date or year","archived":false,"fork":false,"pushed_at":"2023-03-23T18:05:08.000Z","size":83,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-08-16T20:16:23.173Z","etag":null,"topics":["astronomical-algorithms","javascript","labs","seasons","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/postlight.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}},"created_at":"2023-03-07T21:57:03.000Z","updated_at":"2024-04-05T09:33:52.000Z","dependencies_parsed_at":"2023-09-24T06:33:30.029Z","dependency_job_id":null,"html_url":"https://github.com/postlight/seasons","commit_stats":{"total_commits":19,"total_committers":1,"mean_commits":19.0,"dds":0.0,"last_synced_commit":"7fc71bb7a26145930b8f2af75d9493ada8ed784c"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/postlight/seasons","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlight%2Fseasons","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlight%2Fseasons/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlight%2Fseasons/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlight%2Fseasons/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/postlight","download_url":"https://codeload.github.com/postlight/seasons/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlight%2Fseasons/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276613192,"owners_count":25673398,"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","status":"online","status_checked_at":"2025-09-23T02:00:09.130Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["astronomical-algorithms","javascript","labs","seasons","typescript"],"created_at":"2025-06-10T14:40:17.017Z","updated_at":"2025-09-23T16:44:23.473Z","avatar_url":"https://github.com/postlight.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Astronomical Seasons\n\nThis package calculates the astronomical season for a given date or year.\n\nAstronomical seasons are based around natural rotation of the Earth around the sun. Each season begins with either a solstice or an equinox, and which season those represent depends on which side of the equator you're on. Learn more about astronomical and meteorological (month-based) seasons [here](https://www.ncei.noaa.gov/news/meteorological-versus-astronomical-seasons).\n\n**Features**\n\n- Get the current season of a date\n- Get the date and time of the solstice/equinox in a month, which marks the beginning of a season\n  - As a UTC datetime\n  - As a Julian Day\n- Get a list of all the solstices and equinoxes in a given year, which mark the beginning of a new season\n\n## Installation\n\n```bash\nyarn add @postlight/seasons\n\n# or\n\nnpm install @postlight/seasons\n```\n\n## Usage\n\nThe package can be called using import or required, and has been built for both CommonJS and ECMAScript module formats.\n\nBelow example demonstrates how to get the current season of a date.\n\n```javascript\nimport { getCurrentSeason } from \"@postlight/seasons\";\n\nconst currentSeason = getCurrentSeason(new Date());\nconsole.log(currentSeason);\n```\n\n## Functions\n\n`getCurrentSeason(date, isNorthernHemisphere?)`\n\nGets the name of the current season for the date. Since season names are different in each hemisphere, \"isNorthernHemisphere\" is an optional argument and defaults to true. The season is determined on the local timezone, since the UTC date must be converted to a timezone since some solstices and equinoxes are different dates (ex: December 2023).\n\nThis function returns \"spring\", \"summer\", \"winter\", or \"fall\"\n\n`getSeasonStart(monthIndex, year)`\n\nGets the next upcoming equinox or solstice, which is the start of the astronomical season. This returns the date and time in UTC, and it needs to be converted to the local datetime to get the correct season start date.\n\nExample usage to get the December solstice in 2023 for EST timezone:\n\n```javascript\n// Get start of winter in northern hemisphere for EST timezone\nseasons.getSeasonStart(11, 2023).toLocaleString(\"en-US\", {\n  timeZone: \"America/New_York\",\n});\n\n// Should output: 12/21/2023, 10:28:45 PM\n```\n\n```javascript\nconst utcSeasonStart = seasons.getSeasonStart(11, 2023); // result: 2023-12-22T03:28:45.400Z\n\n// Convert UTC season start date to local season start date\nconst localStart = new Date(\n  utcSeasonStart.getFullYear(),\n  utcSeasonStart.getMonth(),\n  utcSeasonStart.getDate()\n);\n\n// If local is EST timezone, should output: 2023-12-21T05:00:00.000Z\n```\n\n`getSeasons(year)`\nReturns a list of all the seasons in a year as UTC dates. These dates will need to be converted to the local datetime to get the correct season start date.\n\nResult format: [march-equinox, june-solstice, september-equinox, december-solstice]\n\n`getSeasonStartJulianDay(monthIndex, year)`\n\nReturns the upcoming solstice or equinox for a month and year as a Julian Day.\n\n`getDateFromJulianDay(julianDay: number)`\n\nConverts a Julian day into a UTC date.\n\n## Sources\n\nBelow are sources that were used to create this astronomical season calculator.\n\n- Astronomical Algorithms by Jean Meeus, 2nd edition\n\n- [US Navy Julian Date Converter](https://aa.usno.navy.mil/calculated/calendardate?ID=AA\u0026jd=2437837.39245\u0026submit=Get+Date)\n\n## License\n\nLicensed under either of the below, at your preference:\n\n- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)\n- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)\n\n---\n\n🔬 A Labs project from your friends at [Postlight](https://postlight.com). Happy coding!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostlight%2Fseasons","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpostlight%2Fseasons","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostlight%2Fseasons/lists"}