cronmath

README

CronMath

A Go library for performing time arithmetic operations on cron expressions. Add or subtract minutes and hours from cron expressions with a simple, fluent API.

📦 Installation

go get github.com/ryutaro-asada/cronmath

📚 Examples

Timezone Adjustment

Convert schedules between timezones:

// Convert UTC to JST (UTC+9)
jstSchedule := cronmath.New("0 3 * * *").Add(cronmath.Hours(9))
fmt.Println(jstSchedule.String()) // "0 12 * * *"

// Convert EST to UTC (EST is UTC-5)
utcSchedule := cronmath.New("0 10 * * *").Add(cronmath.Hours(5))
fmt.Println(utcSchedule.String()) // "0 15 * * *"

// Convert PST to EST (PST is UTC-8, EST is UTC-5)
estSchedule := cronmath.New("0 9 * * *").Add(cronmath.Hours(3))
fmt.Println(estSchedule.String()) // "0 12 * * *"

Staggered Job Scheduling

Create staggered schedules to avoid resource contention:

baseTime := "0 2 * * *" // 2:00 AM

schedules := []struct {
    name   string
    offset cronmath.Duration
}{
    {"primary", 0},
    {"secondary", cronmath.Minutes(15)},
    {"tertiary", cronmath.Minutes(30)},
    {"quaternary", cronmath.Hours(1)},
}

for _, s := range schedules {
    schedule := cronmath.New(baseTime).Add(s.offset)
    fmt.Printf("%s: %s\n", s.name, schedule.String())
}
// Output:
// primary: 0 2 * * *
// secondary: 15 2 * * *
// tertiary: 30 2 * * *
// quaternary: 0 3 * * *

Day Boundary Handling

The library automatically handles transitions across midnight:

// Subtract time crossing midnight backward
result := cronmath.New("30 0 * * *").Sub(cronmath.Hours(1))
fmt.Println(result.String()) // "30 23 * * *"

// Add time crossing midnight forward
result = cronmath.New("30 23 * * *").Add(cronmath.Hours(2))
fmt.Println(result.String()) // "30 1 * * *"

// Complex boundary case
result = cronmath.New("45 23 * * *").
    Add(cronmath.Hours(3)).
    Add(cronmath.Minutes(30))
fmt.Println(result.String()) // "15 3 * * *"

Error Handling Patterns

Different approaches for error handling:

// Method 1: Check error at the end
cm := cronmath.New("invalid cron")
result := cm.Add(cronmath.Hours(1))
if err := result.Error(); err != nil {
    log.Printf("Error: %v", err)
}

// Method 2: Use Result() for combined return
result, err := cronmath.New("0 9 * * *").
    Add(cronmath.Hours(2)).
    Result()
if err != nil {
    return fmt.Errorf("failed to calculate cron: %w", err)
}

// Method 3: Direct CronTime manipulation
cron, err := cronmath.ParseCron("0 9 * * *")
if err != nil {
    return err
}
if err := cron.Add(cronmath.Hours(1)); err != nil {
    return err
}

🎯 Cron Expression Format

This library supports standard 5-field cron expressions:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
* * * * *

Valid Examples

• 0 9 * * * - Every day at 9:00 AM
• 30 14 * * 1-5 - Weekdays at 2:30 PM
• 0 0 1 * * - First day of every month at midnight
• 15 10 * * 6,0 - Weekends at 10:15 AM

⚠️ Limitations

• Only minute and hour fields can be modified - Day, month, and day of week fields remain unchanged
• Wildcards in time fields cannot be adjusted - Expressions like * 9 * * * will return an error
• No support for complex expressions - Ranges (0-30), lists (15,30,45), and steps (*/5) are not supported in minute/hour fields
• No validation of day/month combinations - The library doesn't validate if the resulting date is valid

🧪 Testing

Run tests:

go test ./...

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📮 Support

• 📧 For questions and support, please open an issue
• 🐛 For bug reports, please include a minimal reproducible example
• 💡 For feature requests, please describe your use case

🔗 Links

• Documentation
• Examples
• Releases

Documentation

Index

• type CronMath
  • func New(cronStr string) *CronMath
  • func (cm *CronMath) Add(d Duration) *CronMath
  • func (cm *CronMath) Error() error
  • func (cm *CronMath) String() string
  • func (cm *CronMath) Sub(d Duration) *CronMath
• type CronTime
  • func ParseCron(cronStr string) (*CronTime, error)
  • func (c *CronTime) Add(d time.Duration) error
  • func (c *CronTime) String() string
  • func (c *CronTime) Sub(d time.Duration) error
• type Duration
  • func Hours(n int) Duration
  • func Minutes(n int) Duration

Types

type CronMath

type CronMath struct {
	// contains filtered or unexported fields
}

CronMath provides a fluent interface for cron arithmetic

func New

func New(cronStr string) *CronMath

New creates a new CronMath instance from a cron string

func (*CronMath) Add

func (cm *CronMath) Add(d Duration) *CronMath

Add adds duration to the cron expression

func (*CronMath) Error

func (cm *CronMath) Error() error

Error returns any error that occurred during operations

func (*CronMath) String

func (cm *CronMath) String() string

String returns the resulting cron expression

func (*CronMath) Sub

func (cm *CronMath) Sub(d Duration) *CronMath

Sub subtracts duration from the cron expression

type CronTime

type CronTime struct {
	Minute     string
	Hour       string
	DayOfMonth string
	Month      string
	DayOfWeek  string
}

CronTime represents a cron expression that can be manipulated

func ParseCron

func ParseCron(cronStr string) (*CronTime, error)

ParseCron parses a cron expression string into a CronTime struct

func (*CronTime) Add

func (c *CronTime) Add(d time.Duration) error

Add adds a duration to the cron expression

func (*CronTime) String

func (c *CronTime) String() string

String returns the cron expression as a string

func (*CronTime) Sub

func (c *CronTime) Sub(d time.Duration) error

Sub subtracts a duration from the cron expression

type Duration

type Duration = time.Duration

Duration represents a time duration for cron operations

func Hours

func Hours(n int) Duration

Hours creates a duration of n hours

func Minutes

func Minutes(n int) Duration

Minutes creates a duration of n minutes