{"id":21423243,"url":"https://github.com/watzon/hdur","last_synced_at":"2025-10-18T15:30:04.990Z","repository":{"id":263344637,"uuid":"890068065","full_name":"watzon/hdur","owner":"watzon","description":"A human-friendly duration library for Go that extends the standard time.Duration with calendar-aware units, intuitive parsing, and rich formatting options.","archived":false,"fork":false,"pushed_at":"2024-11-18T09:47:37.000Z","size":38,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-23T07:11:26.249Z","etag":null,"topics":["calendar","calendar-aware","date-time","duration","formatting","go","go-library","golang","human-friendly","parsing","time","time-duration","time-management","time-parsing","utilities"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/watzon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"watzon","patreon":"watzon","open_collective":null,"ko_fi":"watzon","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2024-11-17T23:15:06.000Z","updated_at":"2024-11-18T09:47:41.000Z","dependencies_parsed_at":"2025-01-23T07:11:18.464Z","dependency_job_id":"6b224df0-01c6-41c6-a42a-263d45e928f6","html_url":"https://github.com/watzon/hdur","commit_stats":null,"previous_names":["watzon/hdur"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watzon%2Fhdur","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watzon%2Fhdur/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watzon%2Fhdur/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watzon%2Fhdur/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/watzon","download_url":"https://codeload.github.com/watzon/hdur/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243926678,"owners_count":20370022,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calendar","calendar-aware","date-time","duration","formatting","go","go-library","golang","human-friendly","parsing","time","time-duration","time-management","time-parsing","utilities"],"created_at":"2024-11-22T21:15:18.344Z","updated_at":"2025-10-18T15:29:59.933Z","avatar_url":"https://github.com/watzon.png","language":"Go","funding_links":["https://github.com/sponsors/watzon","https://patreon.com/watzon","https://ko-fi.com/watzon"],"categories":[],"sub_categories":[],"readme":"# hdur (/eɪtʃ.dɜr/)\n\n## Human-Friendly Durations for Go\n\n[![CI](https://github.com/watzon/hdur/actions/workflows/ci.yml/badge.svg)](https://github.com/watzon/hdur/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/watzon/hdur/branch/main/graph/badge.svg)](https://codecov.io/gh/watzon/hdur)\n[![Go Report Card](https://goreportcard.com/badge/github.com/watzon/hdur)](https://goreportcard.com/report/github.com/watzon/hdur)\n[![GoDoc](https://pkg.go.dev/badge/github.com/watzon/hdur)](https://pkg.go.dev/github.com/watzon/hdur)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n`hdur` (Human Duration) is a flexible and intuitive duration library for Go that extends the standard `time.Duration` with calendar-aware features and human-readable parsing. It's designed to make working with durations as natural as possible.\n\n## Features\n\n- 📅 **Calendar-aware duration handling**\n  - Properly handles months and years\n  - Accounts for varying month lengths\n  - Preserves day-of-month when possible\n- 🔍 **Human-readable parsing**\n  - Parse durations like \"1 year 2 months 3 days\"\n  - Flexible unit names (year/yr/y, month/mo/m, etc.)\n  - Handles both full and abbreviated units\n- ⚡ **Rich functionality**\n  - Mathematical operations (add, multiply, divide)\n  - Rounding and truncation\n  - Comparison operations\n  - Time-based calculations\n- 🔄 **Serialization support**\n  - JSON marshaling/unmarshaling\n  - SQL scanning/valuing\n  - Custom format strings\n\n## Installation\n\n```bash\ngo get github.com/watzon/hdur\n```\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"time\"\n    \"github.com/watzon/hdur\"\n)\n\nfunc main() {\n    // Parse a duration string\n    d, err := hdur.ParseDuration(\"1 year 2 months 3 days\")\n    if err != nil {\n        panic(err)\n    }\n\n    // Add to current time\n    future := d.Add(time.Now())\n    fmt.Printf(\"Future date: %v\\n\", future)\n\n    // Create durations using constructors\n    day := hdur.Days(1)\n    week := hdur.Weeks(1)\n    if week.Equal(hdur.Days(7)) {\n        fmt.Println(\"1 week equals 7 days\")\n    }\n\n    // Mathematical operations\n    doubled := day.Mul(2)\n    fmt.Printf(\"Two days: %v\\n\", doubled)\n\n    // Format durations\n    threeDays := hdur.Days(3)\n    fmt.Println(threeDays.Format(\"%d days\"))  // \"3 days\"\n\n    // Use with time.Time\n    start := time.Now()\n    time.Sleep(time.Second)\n    elapsed := hdur.Since(start)\n    fmt.Printf(\"Operation took: %v\\n\", elapsed)\n}\n```\n\n## Usage Examples\n\n### Parsing Durations\n\n```go\n// Multiple ways to specify the same duration\nd1, _ := hdur.ParseDuration(\"1 year 2 months\")\nd2, _ := hdur.ParseDuration(\"1y 2mo\")\nd3, _ := hdur.ParseDuration(\"1yr 2mon\")\n\n// Parse with conjunctions\nd4, _ := hdur.ParseDuration(\"1 year and 2 months\")\n\n// Various time units\nd5, _ := hdur.ParseDuration(\"2weeks 4days 12hours 30minutes 45seconds\")\n```\n\n### Creating Durations\n\n```go\n// Using constructors\nhour := hdur.Hours(1)\nday := hdur.Days(1)\nweek := hdur.Weeks(1)\nmonth := hdur.Months(1)\nyear := hdur.Years(1)\n\n// Using common constants\nthirtySeconds := hdur.Seconds30\ntwentyFourHours := hdur.Hours24\nsixMonths := hdur.Months6\n```\n\n### Time Operations\n\n```go\n// Add duration to time\nfuture := hdur.Months(3).Add(time.Now())\n\n// Get duration between times\nstart := time.Now()\n// ... do something ...\nelapsed := hdur.Since(start)\n\n// Calculate time until future date\ndeadline := time.Date(2024, 12, 31, 0, 0, 0, 0, time.UTC)\nremaining := hdur.Until(deadline)\n```\n\n### Mathematical Operations\n\n```go\n// Multiply duration\ndouble := hdur.Days(1).Mul(2)\nhalf := hdur.Hours(1).Div(2)\n\n// Round duration\nd := hdur.MustParseDuration(\"1h 30m\")\nrounded := d.Round(hdur.Hours(1)) // 2h\n\n// Compare durations\nif d1.Less(d2) {\n    fmt.Println(\"d1 is shorter than d2\")\n}\n```\n\n### Formatting\n\n```go\nd := hdur.MustParseDuration(\"1 year 2 months 3 days 4 hours\")\n\n// Default format\nfmt.Println(d) // \"1y 2mo 3d 4h\"\n\n// Custom format\nfmt.Println(d.Format(\"%y years %M months %d days %h hours\"))\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - see [LICENSE](LICENSE.md) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwatzon%2Fhdur","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwatzon%2Fhdur","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwatzon%2Fhdur/lists"}