diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 950fad7..fea62c5 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -5,7 +5,7 @@ {"id":"quando-5ib","title":"Date inspection methods","description":"Implement date inspection methods for querying metadata about a date.\n\n**Individual Methods:**\n```go\nfunc (d Date) WeekNumber() int\nfunc (d Date) Quarter() int\nfunc (d Date) DayOfYear() int\nfunc (d Date) IsWeekend() bool\nfunc (d Date) IsLeapYear() bool\n```\n\n**Aggregated Method:**\n```go\ntype DateInfo struct {\n WeekNumber int\n Quarter int\n DayOfYear int\n IsWeekend bool\n IsLeapYear bool\n Unix int64\n}\n\nfunc (d Date) Info() DateInfo\n```\n\n**Specifications:**\n- **WeekNumber**: ISO 8601 (Monday first, Week 1 = first week containing Thursday)\n- **Quarter**: 1-4 (Q1=Jan-Mar, Q2=Apr-Jun, Q3=Jul-Sep, Q4=Oct-Dec)\n- **DayOfYear**: 1-366 (considering leap years)\n- **IsWeekend**: Saturday or Sunday (not configurable in Phase 1)\n- **IsLeapYear**: Divisible by 4, except centuries, except divisible by 400\n\n## Acceptance Criteria\n- [ ] WeekNumber() returns ISO 8601 week number\n- [ ] Quarter() returns 1-4\n- [ ] DayOfYear() returns 1-366\n- [ ] IsWeekend() returns true for Sat/Sun\n- [ ] IsLeapYear() returns true for leap years\n- [ ] Info() returns struct with all fields\n- [ ] ISO 8601 week compliance (Week 1 contains Thursday)\n- [ ] Leap year rules correct (4, 100, 400 rule)\n- [ ] Unit tests for all methods\n- [ ] Edge cases: year boundaries, week 53, leap years\n- [ ] Benchmarks meet \u003c1µs target\n- [ ] Godoc for each method with conventions documented","status":"closed","priority":2,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:22:06.966079923+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T20:45:38.905860871+01:00","closed_at":"2026-02-11T20:45:38.905860871+01:00","close_reason":"Closed","dependencies":[{"issue_id":"quando-5ib","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:13.310800388+01:00","created_by":"Oliver Jakoubek"}]} {"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-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":"closed","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-11T21:25:19.094926099+01:00","closed_at":"2026-02-11T21:25:19.094926099+01:00","close_reason":"Closed","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":"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"}]} diff --git a/README.md b/README.md index 994e91b..28206ec 100644 --- a/README.md +++ b/README.md @@ -40,10 +40,11 @@ endOfMonth := quando.Now().EndOf(quando.Month) // Last day of month 23:59:59 nextFriday := quando.Now().Next(time.Friday) prevMonday := quando.Now().Prev(time.Monday) -// Differences -duration := quando.Diff(startDate, endDate) -months := duration.Months() -humanReadable := duration.Human() // "2 years, 3 months, 5 days" +// Human-readable differences +start := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) +end := time.Date(2028, 3, 15, 0, 0, 0, 0, time.UTC) +duration := quando.Diff(start, end) +fmt.Println(duration.Human()) // "2 years, 2 months, 14 days" // Parsing (automatic format detection) date, err := quando.Parse("2026-02-09") @@ -63,6 +64,19 @@ berlin := date.InTimezone("Europe/Berlin") week := date.WeekNumber() // ISO 8601 week number quarter := date.Quarter() // 1-4 dayOfYear := date.DayOfYear() // 1-366 + +// Complex chaining for real-world scenarios +reportDeadline := quando.Now(). + Add(1, quando.Quarters). // Next quarter + EndOf(quando.Quarter). // Last day of that quarter + StartOf(quando.Week). // Monday of that week + Add(-1, quando.Weeks) // One week before + +// Multilingual formatting +dateEN := quando.Now().WithLang(quando.EN) +dateDE := quando.Now().WithLang(quando.DE) +fmt.Println(dateEN.Format(quando.Long)) // "February 9, 2026" +fmt.Println(dateDE.Format(quando.Long)) // "9. Februar 2026" ``` ## Core Concepts @@ -96,6 +110,105 @@ modified := original.Add(1, quando.Days) // original is unchanged ``` +## Why quando? Comparison to time.Time + +### When to Use quando + +Use **quando** when you need: +- **Month-aware arithmetic**: `Add(1, Months)` handles month-end overflow +- **Business logic**: "Next Friday", "End of Quarter", ISO week numbers +- **Human-readable durations**: "2 years, 3 months, 5 days" +- **Fluent API**: Method chaining for complex date calculations +- **Automatic parsing**: Detect ISO, EU, US formats automatically +- **i18n formatting**: Multilingual date formatting (EN, DE, more coming) + +Use **time.Time** when you need: +- Simple clock arithmetic (add 24 hours) +- High-precision timestamps (nanoseconds matter) +- Minimal dependencies (quando is stdlib-only but adds abstraction) +- Low-level system operations + +### Side-by-Side Comparison + +#### Month Arithmetic with Overflow + +```go +// stdlib: Complex and error-prone +t := time.Date(2026, 1, 31, 12, 0, 0, 0, time.UTC) +// Add 1 month manually - need to handle overflow +nextMonth := t.AddDate(0, 1, 0) // March 3! ❌ Unexpected + +// quando: Intuitive and correct +date := quando.From(time.Date(2026, 1, 31, 12, 0, 0, 0, time.UTC)) +nextMonth := date.Add(1, quando.Months) // Feb 28 ✅ Expected +``` + +#### Finding "Next Friday" + +```go +// stdlib: Manual calculation required +t := time.Now() +daysUntilFriday := (int(time.Friday) - int(t.Weekday()) + 7) % 7 +if daysUntilFriday == 0 { + daysUntilFriday = 7 // Never return today +} +nextFriday := t.AddDate(0, 0, daysUntilFriday) + +// quando: One method call +nextFriday := quando.Now().Next(time.Friday) +``` + +#### Human-Readable Duration + +```go +// stdlib: No built-in solution, must implement yourself +start := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) +end := time.Date(2028, 3, 15, 0, 0, 0, 0, time.UTC) +duration := end.Sub(start) +// duration is just time.Duration (2y3m15d shown as "19480h0m0s") ❌ + +// quando: Built-in human formatting +duration := quando.Diff(start, end) +fmt.Println(duration.Human()) // "2 years, 2 months, 14 days" ✅ +``` + +#### Start of Week (Monday) + +```go +// stdlib: Manual calculation +t := time.Now() +weekday := int(t.Weekday()) +if weekday == 0 { // Sunday + weekday = 7 +} +daysToMonday := weekday - 1 +startOfWeek := t.AddDate(0, 0, -daysToMonday) +startOfWeek = time.Date(startOfWeek.Year(), startOfWeek.Month(), + startOfWeek.Day(), 0, 0, 0, 0, startOfWeek.Location()) + +// quando: One method call +startOfWeek := quando.Now().StartOf(quando.Week) +``` + +### Feature Comparison + +Feature | time.Time | quando +--------|-----------|-------- +Basic date/time | ✅ | ✅ +Add/subtract duration | ✅ | ✅ +Add/subtract months (overflow-safe) | ❌ | ✅ +Snap to start/end of period | ❌ | ✅ +Next/Previous weekday | ❌ | ✅ +ISO 8601 week number | ❌ | ✅ +Quarter calculation | ❌ | ✅ +Human-readable duration | ❌ | ✅ +Automatic format parsing | ❌ | ✅ +Relative parsing ("tomorrow") | ❌ | ✅ +i18n formatting | ❌ | ✅ +Fluent API / chaining | ❌ | ✅ +Immutability guarantee | ⚠️ (manual) | ✅ +Testing (Clock abstraction) | ❌ | ✅ + ## Testing quando provides a `Clock` interface for deterministic tests: @@ -110,6 +223,35 @@ clock := quando.NewFixedClock(fixedTime) date := clock.Now() // Always returns Feb 9, 2026 ``` +## Performance + +quando is designed for high performance with zero allocations in hot paths: + +### Benchmark Results + +Operation | Target | Actual | Status +----------|--------|--------|-------- +Add/Sub (Days) | < 1µs | 37 ns | ✅ 27x faster +Add/Sub (Months) | < 1µs | 181 ns | ✅ 5.5x faster +Diff (integer) | < 1µs | 51 ns | ✅ 20x faster +Diff (float) | < 2µs | 155 ns | ✅ 13x faster +Format (ISO/EU/US) | < 5µs | 91 ns | ✅ 55x faster +Format (Long, i18n) | < 10µs | 267 ns | ✅ 37x faster +Parse (automatic) | < 10µs | 106 ns | ✅ 94x faster +Parse (relative) | < 20µs | 581 ns | ✅ 34x faster + +**Key Performance Features:** +- Zero allocations for arithmetic operations (Add, Sub) +- Zero allocations for snap operations (StartOf, EndOf, Next, Prev) +- Zero allocations for date inspection (WeekNumber, Quarter, etc.) +- Minimal allocations for formatting (1-3 per operation) +- Immutable design enables safe concurrent use + +**Run benchmarks:** +```bash +go test -bench=. -benchmem +``` + ## Requirements - Go 1.22 or later