timeparse

Documentation

Overview

Package timeparse provides user-friendly deadline parsing for CLI commands.

This package supports parsing human-readable time expressions into time.Time values. All parsing is done relative to a provided "now" time, making it suitable for testing with fake clocks.

Supported formats:

Tier 1 - Natural Language:

• Relative: "in 30 minutes", "in 2 hours", "in 1 day"
• Tomorrow: "tomorrow", "tomorrow at 6am", "tomorrow at 14:30"
• Weekdays: "next Monday", "next week"

Tier 2 - Simple Date/Time (local timezone):

• Date only: "2026-01-15", "Jan 15, 2026"
• Date + Time: "2026-01-15 14:30", "Jan 15, 2026 2:30pm"

Tier 3 - RFC3339:

• "2026-01-15T14:30:00Z" (UTC)
• "2026-01-15T14:30:00+07:00" (with offset)

Usage:

// Parse relative to current time
deadline, err := timeparse.ParseDeadline("in 30 minutes", time.Now())

// Parse relative to a specific time (useful for testing)
fakeNow := time.Date(2026, 1, 15, 12, 0, 0, 0, time.UTC)
deadline, err := timeparse.ParseDeadline("tomorrow at 6am", fakeNow)

All times are parsed in the local timezone and converted to UTC for internal storage.

Package timeparse provides user-friendly deadline parsing for CLI commands. It supports multiple input formats in a tiered fallback approach:

Tier 1: Natural language relative times

• "in 30 minutes", "in 2 hours", "in 1 day"
• "tomorrow", "tomorrow at 6am", "tomorrow at 14:30"

Tier 2: Simple date/time formats (local timezone)

• "2026-01-15" (date only, midnight)
• "2026-01-15 14:30" (date + time, 24h format)
• "2026-01-15 14:30:00" (with seconds)
• "Jan 15, 2026" (readable date)
• "Jan 15, 2026 14:30" (readable date + time)

Tier 3: Standard RFC3339

• "2026-01-15T14:30:00Z" (UTC)
• "2026-01-15T14:30:00+07:00" (with offset)

All times are parsed in the user's local timezone and converted to UTC for internal storage. Output is always time.Time in UTC.

Index

• func FormatDeadline(t time.Time) string
• func FormatDuration(from, until time.Time) string
• func ParseDeadline(input string, now time.Time) (time.Time, error)

Functions

func FormatDeadline

func FormatDeadline(t time.Time) string

FormatDeadline formats a UTC time for display to the user. Shows both local time and UTC.

func FormatDuration

func FormatDuration(from, until time.Time) string

FormatDuration formats the duration from 'from' until 'until' in a human-readable way.

func ParseDeadline

func ParseDeadline(input string, now time.Time) (time.Time, error)

ParseDeadline parses a user-provided deadline string into a UTC time.Time. It attempts parsing in three tiers: natural language, simple formats, then RFC3339. The 'now' parameter is used as the reference time for relative expressions like "in 30 minutes" or "tomorrow". This allows for deterministic parsing in tests using fake clocks. Returns an error if the input cannot be parsed or if the resulting time is in the past.

Example:

// Parse relative to current time
deadline, err := ParseDeadline("in 30 minutes", time.Now())

// Parse relative to a specific time (useful for testing)
fakeNow := time.Date(2026, 1, 15, 12, 0, 0, 0, time.UTC)
deadline, err := ParseDeadline("tomorrow at 6am", fakeNow)