feat(schedules): add sunset() for the sunsets seen from a place on Earth in @observerly/orderly

[michealroberts]

What This Changes

• Adds sunset(observer), the mirror of sunrise(): the sunsets seen from a place on Earth, one a day on the days the Sun sets, resolved with @observerly/astrometry to the standard almanac convention, the upper limb of the Sun touching the horizon as it sets. It is one export on the walker sunrise() introduced, with the same Observer validation, the same strictly-after walk past polar days and nights, and the same 400-day bound before exhausting.
• Documents it in the README: a row in the At A Glance table, a line in the example, and the prose of "The Sun" now reads for rising and setting alike.
• Corrects the walker's comment on why it asks from the UTC day before the instant's. The reason is that the event astrometry files under a date can fall on the day after it, which a far-western sunset does every day; the earlier comment attributed it to far-eastern sunrises, which the walk handles without that head start.
• Makes the polar wording precise, in the bound's comment, the README, and the sunrise pole test. Measured over ten years at three longitudes: within a twentieth of a degree of the poles astrometry's day-by-day search catches the one crossing a year in some years only, sunrise and sunset alike, and at the poles themselves in about one year in two, leaving gaps of three or four years. From 89.9 degrees outward it catches one every year. The sunrise pole test had described the pole as a place with no sunrise on any day; it exhausts because the next sunrise astrometry finds from that solstice is in March 2029, well past the bound, and its comment and name now say so.

Notes For Reviewers

• Sunsets key to UTC dates later than sunrises: the sunset filed under a date lies between 0.2 and 36 hours after its midnight, against 12 hours before to 24.1 after for a sunrise. Honolulu's solstice sunset is filed under 21 June and happens at 05:16 UTC on the 22nd, and a test pins that the walk finds it from midnight on the 22nd. Scanning 33 latitudes by 13 longitudes over 800 days found no sunset preceding the day before's and no duplicates, so the day of slack the walk already had is exactly what sunset needs too.
• The two-day margin at the end of the Date range matters more for sunset. Asked for the last representable day, astrometry throws for any observer more than 30 degrees west of Greenwich for a sunset, against 150 for a sunrise, and never throws for the day before. The horizon comment now states both figures, and a far-west sunset test guards the margin; with one day clear it throws Invalid time value.
• There is no pole exhaustion test for sunset: the bound is shared code that the sunrise pole test covers, and whether a given instant at the pole exhausts depends on which years astrometry happens to catch.
• Expected instants are astrometry 0.69.0's own, pinned to the millisecond and checked against the almanac to the minute: London 21:21 BST at the solstice and 16:02 GMT at New Year, Auckland 17:11 NZST, Honolulu 19:16 HST, and Tromsø's polar day and night. A year-long oracle test replays astrometry day by day for Tromsø.
• The type-aware lint reports one new pedantic prefer-readonly-parameter-types warning, on the new export's parameter, the same one every schedule constructor carries. No other warning is new.

Checklist

• Tests cover the change, and run inside workerd
• A changeset is included, or the change is not one a consumer would notice
• No Node built-ins were introduced

[Copilot]

🟡 Changes recommended

Two updated doc comments (in src/schedules/sun.ts and README.md) appear inconsistent with the repository’s existing pole behavior tests for sunrise().

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a new sunset(observer) schedule alongside the existing sunrise() schedule, exposing it through the public exports and documenting/validating its day-by-day walk behavior (including edge-of-Date-range behavior) with dedicated tests.

Changes:

• Add sunset() schedule implemented via the existing shared day-walk logic in src/schedules/sun.ts.
• Add comprehensive vitest coverage for sunset behavior across dates, longitudes, polar conditions, and Date-range horizons.
• Update README and ship a minor changeset to document and publish the new API.

File summaries

File	Description
src/schedules/sun.ts	Adds getSunset integration and exports sunset() via the existing walk/validation logic; updates related explanatory comments.
src/schedules/index.ts	Re-exports sunset from the schedules package surface.
src/index.ts	Re-exports sunset from the library’s top-level API.
tests/sunset.spec.ts	Adds functional/purity/validation tests for sunset() in common scenarios.
tests/sunset-horizons.spec.ts	Adds polar-day/night and Date-range horizon tests for sunset() (including far-west behavior).
README.md	Documents sunset() in the “At a Glance” table and “The Sun” section with example usage.
.changeset/add-sunset.md	Declares a minor release for the new exported schedule.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

Implementation and tests appear consistent with existing sunrise semantics, with only a minor test-description grammar nit noted.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 1
• Review effort level: Lite