The timezone problem that breaks prod once a year
`time.Now()` in most languages gives you the server's local time. Convert to UTC, store in the database, convert back to local on display. This works 99% of the time. The 1% failure: DST transitions. A cron job scheduled at 2:30 AM on the DST 'spring forward' day runs twice or not at all. A date 7 days in the future shows the wrong hour because the DST offset changes between now and then. GoTz handles these edge cases by using IANA timezone IDs ('America/New_York') instead of fixed offsets ('-05:00').
IANA database: the source of truth for time
GoTz wraps the IANA timezone database (tzdata). This database tracks every timezone change in history: when each country adopted DST, when they changed DST rules, when they changed their standard offset. Example: Samoa skipped December 30, 2011 entirely (switched from -11 to +13). The IANA database knows this. A fixed -11:00 offset does not. GoTz loads the IANA database and applies it correctly to all date calculations.
Performance and the embedded database
GoTz embeds the IANA database in the binary (500KB). No runtime HTTP calls to an external timezone service. No filesystem dependency on `/usr/share/zoneinfo`. This matters for Docker containers that run on scratch images with no tzdata installed. The embedded database updates with the library version: bump GoTz to get the latest IANA rules.
Common use cases where GoTz saves you
Scheduling: 'send this notification at 9 AM in the user's timezone.' Billing: 'charge at midnight on the first of the month in the account's timezone.' Reporting: 'show revenue for yesterday in the store's timezone, not the server's UTC.' Cron jobs: 'run at 2 AM daily, handling DST transitions correctly.' All of these have edge cases that raw `time.Time` with fixed offsets handles incorrectly.
GoTz vs built-in time vs moment.js
GoTz (Go): handles DST, embeds IANA database, 500KB overhead. Best for Go services. Python `pytz`: same features, larger dependency, actively maintained. Best for Python. JavaScript `luxon`: same features, replaces moment.js, handles DST correctly. Use luxon instead of moment.js.
