diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 11fc3de..e3debdf 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -6,7 +6,7 @@ {"id":"quando-5ol","title":"Format presets and constants","description":"Implement preset format constants and Format() method.\n\n**API:**\n```go\ntype Format int\n\nconst (\n ISO Format = iota // \"2026-02-09\"\n EU // \"09.02.2026\"\n US // \"02/09/2026\"\n Long // \"February 9, 2026\" (language-dependent)\n RFC2822 // \"Mon, 09 Feb 2026 00:00:00 +0000\"\n)\n\nfunc (d Date) Format(format Format) string\n```\n\n**Language Dependency:**\n- ISO, EU, US, RFC2822: Always language-independent\n- Long: Uses Lang setting\n - EN: \"February 9, 2026\"\n - DE: \"9. Februar 2026\"\n\n**Implementation:**\n- Map Format constants to Go layout strings\n- Use Lang() setting for Long format\n- Delegate to time.Format() internally\n\n## Acceptance Criteria\n- [ ] Format type and constants defined\n- [ ] Format() method implemented\n- [ ] ISO format outputs \"YYYY-MM-DD\"\n- [ ] EU format outputs \"DD.MM.YYYY\"\n- [ ] US format outputs \"MM/DD/YYYY\"\n- [ ] RFC2822 format correct\n- [ ] Long format respects Lang setting (EN and DE)\n- [ ] Non-Long formats ignore Lang setting\n- [ ] Unit tests for all formats\n- [ ] Unit tests for Long with both EN and DE\n- [ ] Benchmark meets \u003c5µs without i18n, \u003c10µs with i18n\n- [ ] Godoc for each format constant\n- [ ] Example tests showing each format","status":"closed","priority":2,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:53.217816331+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T20:11:47.455205479+01:00","closed_at":"2026-02-11T20:11:47.455205479+01:00","close_reason":"Closed","dependencies":[{"issue_id":"quando-5ol","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:12.164278602+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-5ol","depends_on_id":"quando-zbr","type":"blocks","created_at":"2026-02-11T16:23:12.20045666+01:00","created_by":"Oliver Jakoubek"}]} {"id":"quando-6c3","title":"CI/CD pipeline setup","description":"Set up GitHub Actions CI/CD pipeline for automated testing and quality checks.\n\n**CI Workflow:**\n- Run on push and pull requests\n- Test on multiple Go versions (1.22, 1.23, latest)\n- Test on multiple platforms (Linux, macOS, Windows)\n- Run go fmt check\n- Run go vet\n- Run tests with coverage\n- Run benchmarks (informational)\n- Optional: golangci-lint\n\n**Coverage Reporting:**\n- Generate coverage report\n- Fail if coverage \u003c95% for core calculation functions\n- Optional: Upload to codecov.io or similar\n\n**Performance Monitoring:**\n- Run benchmarks on each commit\n- Report benchmark results (informational, no fail)\n\n## Acceptance Criteria\n- [ ] .github/workflows/ci.yml created\n- [ ] Tests run on push and PR\n- [ ] Multi-version Go support (1.22+)\n- [ ] Multi-platform support (Linux, macOS, Windows)\n- [ ] go fmt check passes\n- [ ] go vet check passes\n- [ ] Tests run with coverage report\n- [ ] Coverage requirement enforced (95%+)\n- [ ] Benchmarks run (informational)\n- [ ] CI badge in README (if applicable)","status":"tombstone","priority":3,"issue_type":"task","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:22:51.928117055+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T19:21:16.246958875+01:00","dependencies":[{"issue_id":"quando-6c3","depends_on_id":"quando-r1o","type":"blocks","created_at":"2026-02-11T16:23:16.259739409+01:00","created_by":"Oliver Jakoubek"}],"deleted_at":"2026-02-11T19:21:16.246958875+01:00","deleted_by":"daemon","delete_reason":"delete","original_type":"task"} {"id":"quando-6x3","title":"Documentation and examples","description":"Complete documentation including README, godoc, and example code.\n\n**README.md Contents:**\n- Project overview and vision\n- Installation instructions (go get)\n- Quick start examples\n- Core features showcase\n- Performance characteristics\n- Comparison to time.Time\n- Contributing guidelines\n- License\n\n**Godoc Requirements:**\n- Every exported type/function documented\n- Godoc comments start with type/function name\n- Complex behaviors explained (month-end overflow, DST, etc.)\n- Edge cases noted where applicable\n\n**Example Tests:**\n- Example_basicArithmetic\n- Example_monthEndOverflow\n- Example_snapOperations\n- Example_diffCalculation\n- Example_humanFormat\n- Example_parsing\n- Example_formatting\n- Example_timezoneConversion\n- Example_chainedOperations\n\n**Code Examples in README:**\n- Complex chaining\n- Month-end handling\n- Human-readable diffs\n- Timezone-aware operations\n- Comparison with stdlib\n\n## Acceptance Criteria\n- [ ] README.md complete with all sections\n- [ ] Installation instructions clear\n- [ ] At least 5 code examples in README\n- [ ] All exported items have godoc comments\n- [ ] Godoc comments follow conventions (name first)\n- [ ] At least 8 example tests\n- [ ] Examples demonstrate key features\n- [ ] Edge cases documented in relevant godoc\n- [ ] Comparison table with time.Time\n- [ ] Contributing guidelines (if open source)","status":"open","priority":3,"issue_type":"task","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:22:45.693695262+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:22:45.693695262+01:00","dependencies":[{"issue_id":"quando-6x3","depends_on_id":"quando-r1o","type":"blocks","created_at":"2026-02-11T16:23:16.222906911+01:00","created_by":"Oliver Jakoubek"}]} -{"id":"quando-7m5","title":"MustParse convenience function","description":"Implement MustParse() convenience function that panics on error (for tests/initialization).\n\n**API:**\n```go\nfunc MustParse(s string) Date\n```\n\n**Behavior:**\n- Calls Parse() internally\n- Returns Date on success\n- Panics on error (with clear panic message)\n\n**Use Cases:**\n- Test fixtures\n- Static initialization\n- Configuration files where values are known-good\n\n**Documentation:**\n- MUST clearly document that this function panics\n- MUST recommend using Parse() in production code\n- MUST show test usage examples\n\n## Acceptance Criteria\n- [ ] MustParse() implemented\n- [ ] Returns Date on successful parse\n- [ ] Panics with clear message on error\n- [ ] Godoc clearly warns about panic behavior\n- [ ] Godoc recommends Parse() for production\n- [ ] Example test showing test fixture usage\n- [ ] Unit tests verifying panic on invalid input","status":"open","priority":3,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:46.007442996+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:21:46.007442996+01:00","dependencies":[{"issue_id":"quando-7m5","depends_on_id":"quando-gr5","type":"blocks","created_at":"2026-02-11T16:23:11.340600075+01:00","created_by":"Oliver Jakoubek"}]} +{"id":"quando-7m5","title":"MustParse convenience function","description":"Implement MustParse() convenience function that panics on error (for tests/initialization).\n\n**API:**\n```go\nfunc MustParse(s string) Date\n```\n\n**Behavior:**\n- Calls Parse() internally\n- Returns Date on success\n- Panics on error (with clear panic message)\n\n**Use Cases:**\n- Test fixtures\n- Static initialization\n- Configuration files where values are known-good\n\n**Documentation:**\n- MUST clearly document that this function panics\n- MUST recommend using Parse() in production code\n- MUST show test usage examples\n\n## Acceptance Criteria\n- [ ] MustParse() implemented\n- [ ] Returns Date on successful parse\n- [ ] Panics with clear message on error\n- [ ] Godoc clearly warns about panic behavior\n- [ ] Godoc recommends Parse() for production\n- [ ] Example test showing test fixture usage\n- [ ] Unit tests verifying panic on invalid input","status":"closed","priority":3,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:46.007442996+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T20:54:19.638519056+01:00","closed_at":"2026-02-11T20:54:19.638519056+01:00","close_reason":"Closed","dependencies":[{"issue_id":"quando-7m5","depends_on_id":"quando-gr5","type":"blocks","created_at":"2026-02-11T16:23:11.340600075+01:00","created_by":"Oliver Jakoubek"}]} {"id":"quando-91w","title":"Project setup and structure","description":"Set up initial project structure, module, and tooling.\n\n**Repository Structure:**\n```\nquando/\n├── quando.go # Package-level functions\n├── date.go # Date type and core methods\n├── arithmetic.go # Add, Sub\n├── snap.go # StartOf, EndOf, Next, Prev\n├── diff.go # Duration type, Diff\n├── inspect.go # WeekNumber, Quarter, etc.\n├── format.go # Formatting\n├── parse.go # Parsing\n├── clock.go # Clock abstraction\n├── i18n.go # Internationalization\n├── errors.go # Error types\n├── internal/calc/ # Internal helpers\n├── *_test.go # Unit tests\n├── example_test.go # Godoc examples\n├── bench_test.go # Benchmarks\n├── go.mod\n├── go.sum\n├── README.md\n├── LICENSE # MIT\n└── .github/workflows/ci.yml\n```\n\n**Go Module:**\n- Module path: code.beautifulmachines.dev/quando\n- Go version: 1.22+\n- Zero dependencies (stdlib only)\n\n**Tooling:**\n- go fmt\n- go vet\n- golangci-lint (optional)\n\n## Acceptance Criteria\n- [ ] go.mod initialized with correct module path\n- [ ] Go 1.22+ specified in go.mod\n- [ ] Directory structure created\n- [ ] README.md with project overview\n- [ ] LICENSE file (MIT)\n- [ ] .gitignore for Go projects\n- [ ] Basic CI/CD workflow (if applicable)","status":"closed","priority":0,"issue_type":"task","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:22:30.054241058+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:28:17.730717812+01:00","closed_at":"2026-02-11T16:28:17.730717812+01:00","close_reason":"Closed","comments":[{"id":1,"issue_id":"quando-91w","author":"Oliver Jakoubek","text":"Plan: 1) Initialize go.mod with module path code.beautifulmachines.dev/quando and Go 1.22+, 2) Create internal/calc/ directory structure, 3) Write comprehensive README.md, 4) Add MIT LICENSE, 5) Populate .gitignore for Go, 6) Create GitHub Actions CI workflow for testing and linting","created_at":"2026-02-11T15:26:35Z"}]} {"id":"quando-95w","title":"Custom layout formatting","description":"Implement FormatLayout() for custom format layouts using Go's standard layout format.\n\n**API:**\n```go\nfunc (d Date) FormatLayout(layout string) string\n```\n\n**Behavior:**\n- Uses Go's reference date format (Mon Jan 2 15:04:05 MST 2006)\n- Respects Lang() setting for month/weekday names\n- Delegates to time.Format() with translations applied\n\n**Examples:**\n```go\n// English (default)\ndate.FormatLayout(\"Monday, 2. January 2006\")\n// → \"Monday, 9. February 2026\"\n\n// German\ndate.Lang(LangDE).FormatLayout(\"Monday, 2. January 2006\")\n// → \"Montag, 9. Februar 2026\"\n```\n\n**Implementation:**\n- Replace month/weekday names based on Lang setting\n- Handle both full and abbreviated names\n- Preserve all other layout characters\n\n## Acceptance Criteria\n- [ ] FormatLayout() implemented\n- [ ] Uses Go's standard layout format\n- [ ] Default (EN) outputs English month/weekday names\n- [ ] DE lang outputs German month/weekday names\n- [ ] Full names translated (Monday, January)\n- [ ] Abbreviated names translated (Mon, Jan)\n- [ ] Non-date characters preserved in layout\n- [ ] Unit tests for various layouts\n- [ ] Unit tests for both EN and DE\n- [ ] Benchmark meets \u003c10µs target with i18n\n- [ ] Godoc with Go layout format reference\n- [ ] Example tests showing custom layouts","status":"closed","priority":2,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:59.18488929+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T20:34:48.639373428+01:00","closed_at":"2026-02-11T20:34:48.639373428+01:00","close_reason":"Closed","dependencies":[{"issue_id":"quando-95w","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:12.24298936+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-95w","depends_on_id":"quando-zbr","type":"blocks","created_at":"2026-02-11T16:23:12.275497777+01:00","created_by":"Oliver Jakoubek"}]} {"id":"quando-9sf","title":"Snap operations: Next and Prev weekday","description":"Implement Next and Prev methods to jump to next/previous occurrence of a weekday.\n\n**API:**\n```go\nfunc (d Date) Next(weekday time.Weekday) Date\nfunc (d Date) Prev(weekday time.Weekday) Date\n```\n\n**Critical Behavior:**\n- **Next(Monday)**: Always NEXT Monday, never today (even if today is Monday)\n- **Prev(Friday)**: Always PREVIOUS Friday, never today (even if today is Friday)\n- Preserves time of day from source date\n\n**Examples:**\n- Monday calling Next(Monday) → next Monday (7 days later)\n- Monday calling Prev(Monday) → previous Monday (7 days earlier)\n- Tuesday calling Next(Monday) → next Monday (6 days later)\n\n## Acceptance Criteria\n- [ ] Next() implemented for all weekdays\n- [ ] Prev() implemented for all weekdays\n- [ ] Next() never returns today (always future)\n- [ ] Prev() never returns today (always past)\n- [ ] Time of day preserved from source\n- [ ] Edge case: Same weekday correctly skips to next/prev week\n- [ ] Unit tests for all weekday combinations\n- [ ] Tests for same weekday edge case\n- [ ] Benchmarks meet \u003c1µs target\n- [ ] Godoc comments with same-weekday behavior example","status":"closed","priority":1,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:20:58.320692116+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T17:33:58.411235677+01:00","closed_at":"2026-02-11T17:33:58.411235677+01:00","close_reason":"Closed","dependencies":[{"issue_id":"quando-9sf","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:07.357069002+01:00","created_by":"Oliver Jakoubek"}],"comments":[{"id":6,"issue_id":"quando-9sf","author":"Oliver Jakoubek","text":"Plan: 1) Add Next(weekday) and Prev(weekday) methods to snap.go, 2) Implement logic to ALWAYS skip to next/prev occurrence (never return today), 3) Preserve time of day from source date, 4) Handle same-weekday edge case (Monday.Next(Monday) = next Monday), 5) Write comprehensive unit tests for all weekday combinations, 6) Add tests specifically for same-weekday edge case, 7) Add benchmarks, 8) Ensure godoc comments with examples","created_at":"2026-02-11T16:31:43Z"}]} diff --git a/example_test.go b/example_test.go index de05751..f931c66 100644 --- a/example_test.go +++ b/example_test.go @@ -916,3 +916,39 @@ func ExampleDate_Info_leapYear() { // Is weekend: false // Is leap year: true } + +// ExampleMustParse demonstrates basic usage in tests and initialization +func ExampleMustParse() { + // Use in test fixtures or static initialization + date := quando.MustParse("2026-02-09") + fmt.Println(date) + // Output: 2026-02-09 00:00:00 +} + +// ExampleMustParse_testFixture demonstrates using MustParse in test fixtures +func ExampleMustParse_testFixture() { + // Common pattern in tests - no error handling needed + startDate := quando.MustParse("2026-01-01") + endDate := quando.MustParse("2026-12-31") + + fmt.Printf("Start: %v\n", startDate.Time().Format("2006-01-02")) + fmt.Printf("End: %v\n", endDate.Time().Format("2006-01-02")) + // Output: + // Start: 2026-01-01 + // End: 2026-12-31 +} + +// ExampleMustParse_staticInit demonstrates static initialization pattern +func ExampleMustParse_staticInit() { + // Pattern for package-level constants + var ( + epoch = quando.MustParse("1970-01-01") + y2k = quando.MustParse("2000-01-01") + ) + + fmt.Printf("Epoch: %v\n", epoch.Time().Year()) + fmt.Printf("Y2K: %v\n", y2k.Time().Year()) + // Output: + // Epoch: 1970 + // Y2K: 2000 +} diff --git a/parse.go b/parse.go index 7f38204..829608a 100644 --- a/parse.go +++ b/parse.go @@ -128,6 +128,46 @@ func Parse(s string) (Date, error) { return Date{}, fmt.Errorf("parsing date %q: no matching format: %w", s, ErrInvalidFormat) } +// MustParse parses a date string using automatic format detection and panics on error. +// +// This is a convenience wrapper around Parse() for use in tests and initialization code +// where the input is known to be valid. If parsing fails, it panics with the parse error. +// +// IMPORTANT: This function panics on error. For production code that needs to handle +// errors gracefully, use Parse() instead. +// +// Supported formats (same as Parse): +// - ISO format: "2026-02-09" (YYYY-MM-DD) +// - ISO with slash: "2026/02/09" (YYYY/MM/DD) +// - EU format: "09.02.2026" (DD.MM.YYYY) +// - RFC2822: "Mon, 09 Feb 2026 00:00:00 +0000" +// +// Use cases: +// - Test fixtures: date := quando.MustParse("2026-02-09") +// - Static initialization: var StartDate = quando.MustParse("2026-01-01") +// - Configuration where dates are validated at load time +// +// Example (test fixture): +// +// func TestSomething(t *testing.T) { +// date := quando.MustParse("2026-02-09") +// // Use date without error handling... +// } +// +// Example (static initialization): +// +// var ( +// EpochDate = quando.MustParse("1970-01-01") +// Y2K = quando.MustParse("2000-01-01") +// ) +func MustParse(s string) Date { + date, err := Parse(s) + if err != nil { + panic(fmt.Sprintf("quando.MustParse(%q): %v", s, err)) + } + return date +} + // isYearPrefix checks if the first 4 characters represent a valid year (>= 1000). // This helps distinguish YYYY/MM/DD from DD/MM/YYYY or MM/DD/YYYY. func isYearPrefix(s string) bool { diff --git a/parse_test.go b/parse_test.go index 9e9b608..2e00cd6 100644 --- a/parse_test.go +++ b/parse_test.go @@ -2,6 +2,7 @@ package quando import ( "errors" + "fmt" "testing" "time" ) @@ -855,3 +856,71 @@ func BenchmarkParseRelativeOffset(b *testing.B) { _, _ = ParseRelativeWithClock("+2 days", clock) } } + +func TestMustParse_Success(t *testing.T) { + tests := []struct { + name string + input string + expected time.Time + }{ + {"ISO format", "2026-02-09", time.Date(2026, 2, 9, 0, 0, 0, 0, time.UTC)}, + {"ISO with slash", "2026/02/09", time.Date(2026, 2, 9, 0, 0, 0, 0, time.UTC)}, + {"EU format", "09.02.2026", time.Date(2026, 2, 9, 0, 0, 0, 0, time.UTC)}, + {"RFC2822", "Sun, 09 Feb 2026 00:00:00 +0000", time.Date(2026, 2, 9, 0, 0, 0, 0, time.UTC)}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + result := MustParse(tt.input) + + if !result.Time().Equal(tt.expected) { + t.Errorf("MustParse(%q) = %v, want %v", tt.input, result.Time(), tt.expected) + } + }) + } +} + +func TestMustParse_Panic(t *testing.T) { + tests := []struct { + name string + input string + }{ + {"empty string", ""}, + {"invalid format", "not-a-date"}, + {"ambiguous slash format", "01/02/2026"}, + {"invalid date", "2026-13-01"}, + {"malformed", "2026-02-"}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + defer func() { + if r := recover(); r == nil { + t.Errorf("MustParse(%q) expected panic, but didn't panic", tt.input) + } + }() + + // This should panic + _ = MustParse(tt.input) + }) + } +} + +func TestMustParse_PanicMessage(t *testing.T) { + defer func() { + if r := recover(); r != nil { + msg := fmt.Sprint(r) + // Verify panic message includes the input string + if !containsSubstring(msg, "invalid-input") { + t.Errorf("panic message %q should include input string %q", msg, "invalid-input") + } + if !containsSubstring(msg, "MustParse") { + t.Errorf("panic message %q should include function name %q", msg, "MustParse") + } + } else { + t.Error("expected panic but didn't panic") + } + }() + + MustParse("invalid-input") +}