go-naturaldate

go-naturaldate is a package for the Go programming language that takes plain-English phrases like "yesterday at 10am" or "three days ago" and converts them into actual dates and times that a computer can understand. It was built for a command-line log search tool, where people need to type quick time ranges without fumbling with exact date formats.

Instead of forcing users to enter something rigid like "2024-01-15T10:00:00Z," it lets them write the way they naturally speak. You can say "last Sunday at 5:30pm," "next January," "December 25th at 7:30am," or even "remind me on the 25th of December at 7:30am." The library ignores extra words around the date expression, so a sentence like "Restart the server in 5 days from now" still works — it picks out the relevant time reference and figures out the rest. Written-out numbers like "two weeks" are handled just as well as numeric ones.

The main use case is any application where people type into a search box or command line and you want the experience to feel forgiving and natural. A log search tool is the original motivation: an engineer investigating an issue wants to pull up logs from "yesterday at 10am" without stopping to calculate timestamps. The same idea could apply to a chat bot that schedules reminders, a reporting dashboard with a time-range filter, or any text interface where users express relative time concepts like "5 minutes ago" or "last month."

One small but thoughtful detail: when someone types an ambiguous word like "Sunday" or "September," the library defaults to the past — meaning the most recent one. A developer can flip this default direction if their app expects future-looking input instead.