GoTime 🕐🕑🕒

Intuitive time manipulation for Go - Making date/time operations as simple as they should be.

GoTime extends Go's standard time package with human-friendly operations that developers actually need in real-world applications. It leverages Go's powerful time handling while providing an intuitive API that makes working with dates and times a breeze.

Quick Example

import "github.com/maniartech/gotime/v2"

// Intuitive formatting - no more "2006-01-02"!
formatted := gotime.Format(time.Now(), "yyyy-mm-dd hh:ii:ss")
// → "2025-07-07 14:30:45"

// Easy format conversion
converted, _ := gotime.Convert("07/07/2025", "mm/dd/yyyy", "mmmm dt, yyyy")
// → "July 7th, 2025"

// Human-readable relative time
timeAgo := gotime.TimeAgo(time.Now().Add(-5 * time.Minute))
// → "5 minutes ago"

// Simple date arithmetic
nextBusinessDay := gotime.WorkDay(1, time.Now())
tenDaysFromNow := gotime.Days(10, time.Now())

Why GoTime?

The Problem: Go's time formatting is cryptic and error-prone

// Standard Go - Who remembers this?
time.Now().Format("2006-01-02 15:04:05")  // 😵‍💫

The Solution: Human-readable format specifiers

// GoTime - Intuitive and memorable
gotime.Format(time.Now(), "yyyy-mm-dd hh:ii:ss")  // 😊

Key Benefits

| What You Get | Standard Go | GoTime | |-------------|-------------|---------| | Natural Syntax | Cryptic 2006-01-02 | NITES yyyy-mm-dd | | Relative Time | 15+ lines of code | TimeAgo() | | Format Conversion | Parse + Format | Convert() | | Date Arithmetic | Complex calculations | WorkDay(), Days() | | Business Logic | Manual calculations | Built-in helpers |

Perfect For

• Web APIs - Consistent date formatting across endpoints
• Reports - Human-readable timestamps and date ranges
• Business Logic - Working day calculations, relative dates
• Data Processing - Converting between date formats
• User Interfaces - "2 hours ago" style timestamps

Installation

go get github.com/maniartech/gotime/v2@v2.0.3

Requirements: Go 1.13+ • Zero dependencies • TinyGo compatible*

Core Features

Intuitive Formatting

// Remember yyyy-mm-dd, not 2006-01-02
formatted := gotime.Format(time.Now(), "mmmm dt, yyyy")
// → "July 7th, 2025"

Smart Date Parsing

date, _ := gotime.Parse("2025-07-07", "yyyy-mm-dd")
date, _ := gotime.Parse("07/07/2025", "mm/dd/yyyy")

One-Line Format Conversion

iso, _ := gotime.Convert("07/07/2025", "mm/dd/yyyy", "yyyy-mm-dd")
// → "2025-07-07"

Human-Friendly Relative Time

gotime.TimeAgo(fiveMinutesAgo)  // → "5 minutes ago"
gotime.TimeAgo(nextWeek)        // → "Next week"

Business Date Calculations

nextBusinessDay := gotime.WorkDay(1, time.Now())
businessDaysCount := gotime.NetWorkDays(startDate, endDate)

Documentation

Complete Documentation

Quick Links

• 5-Minute Quick Start - Get productive immediately
• Why GoTime? - Detailed comparison with standard library
• NITES Format Specifiers - Complete NITES reference
• API Reference - All functions with examples
• Real-World Examples - Web APIs, databases, business logic

By Use Case

• Web Development - APIs, user timestamps
• Database Integration - Custom types, queries
• Business Applications - Invoices, schedules
• Analytics - Time-series, monitoring

Quality & Reliability

• 100% Test Coverage — Every function is thoroughly tested
• 250+ Automated Test Cases — Industry-grade reliability
• ✓ Production Ready — Used in real-world applications
• ✓ Zero Dependencies — Only uses Go standard library
• ✓ TinyGo Compatible — Works in embedded and WebAssembly*
• ✓ MIT Licensed — Free for commercial use

TinyGo Compatibility*

GoTime's core library is designed to be compatible with TinyGo for use in embedded and WebAssembly environments. Test helpers and some internal utilities use reflect and runtime and are not TinyGo compatible, but these are not required for end users. To build with TinyGo, you must use a Go version supported by TinyGo (currently Go 1.19–1.22). See examples/tinygo/main.go for a working example.

Contributing

Contributions are welcome! Please ensure your code includes tests and follows existing patterns.

Found an issue? Open an issue Want to contribute? See our contribution guidelines

License

MIT Licensed - see LICENSE for details.

---

Browse Documentation | Star on GitHub | Report Issues