feat: introduce TemporalAccessor interface and TemporalValue for type-safe field queries

Replace GetFieldInt64() method with GetField() that returns TemporalValue,
providing a more robust and type-safe API for querying temporal fields.

Breaking Changes:
- LocalDate.GetFieldInt64(field Field) int64 → GetField(field Field) TemporalValue
- LocalTime.GetFieldInt64(field Field) int64 → GetField(field Field) TemporalValue
- LocalDateTime.GetFieldInt64(field Field) int64 → GetField(field Field) TemporalValue

New Features:
- Add TemporalAccessor interface for universal temporal object querying
- Add TemporalValue type with validation states (Valid/Unsupported/Overflow)
- All temporal types now implement TemporalAccessor interface
- Enable generic programming with temporal types via interface

Benefits:
- Type-safe field access with explicit validation
- Clear distinction between unsupported fields and zero values
- Better error handling and debugging experience
- Future-proof API ready for overflow detection
- Consistent query pattern across all temporal types

Files Changed:
- temporal_accessor.go: new interface definition
- temporal_value.go: new value wrapper with validation
- local_date.go: implement GetField() with TemporalValue
- local_time.go: implement GetField() with TemporalValue
- local_date_time.go: implement GetField() with TemporalValue
- field_test.go: comprehensive tests for new API
- example_test.go: updated examples demonstrating new usage
- README.md: updated documentation with new API and examples

Author: iseki0

README.md

@@ -17,14 +17,17 @@ A Go implementation inspired by Java's `java.time` package (JSR-310), providing
 - ⏰ **LocalTime**: Time without date (e.g., `14:30:45.123456789`)
 - 📆 **LocalDateTime**: Date-time (e.g., `2024-03-15T14:30:45.123456789`)
 - 🔢 **Field**: Enumeration of date-time fields (like Java's `ChronoField`)
+- 🔍 **TemporalAccessor**: Universal interface for querying temporal objects
+- 📊 **TemporalValue**: Type-safe wrapper for field values with validation state
 
 ### Key Features
 
 - ✅ **ISO 8601 basic format** support (yyyy-MM-dd, HH:mm:ss[.nnnnnnnnn], combined with 'T')
 - ✅ **Java.time compatible formatting**: Fractional seconds aligned to 3-digit boundaries (milliseconds, microseconds, nanoseconds)
 - ✅ **Full JSON and SQL** database integration
 - ✅ **Date arithmetic**: Add/subtract days, months, years with overflow handling
-- ✅ **Field access**: Get any field value (year, month, hour, nano-of-day, etc.)
+- ✅ **Type-safe field access**: Query any field with `TemporalValue` return type that validates support and overflow
+- ✅ **TemporalAccessor interface**: Universal query pattern across all temporal types
 - ✅ **Zero-copy text marshaling** with `encoding.TextAppender`
 - ✅ **Immutable**: All operations return new values
 - ✅ **Type-safe**: Compile-time safety with distinct types
@@ -80,9 +83,9 @@ func main() {
 }
 ```
 
-### Field Access
+### Field Access with TemporalValue
 
-Access individual date-time fields using the `Field` enumeration:
+Access individual date-time fields using the `Field` enumeration with type-safe `TemporalValue` returns:
 
 ```go
 date := goda.MustNewLocalDate(2024, goda.March, 15)
@@ -91,16 +94,73 @@ date := goda.MustNewLocalDate(2024, goda.March, 15)
 fmt.Println(date.IsSupportedField(goda.DayOfMonth))  // true
 fmt.Println(date.IsSupportedField(goda.HourOfDay))   // false
 
-// Get field values
-year := date.GetFieldInt64(goda.YearField)           // 2024
-dayOfWeek := date.GetFieldInt64(goda.DayOfWeekField) // 5 (Friday)
-dayOfYear := date.GetFieldInt64(goda.DayOfYear)      // 75
-epochDays := date.GetFieldInt64(goda.EpochDay)       // Days since Unix epoch
+// Get field values with validation
+year := date.GetField(goda.YearField)
+if year.Valid() {
+    fmt.Println("Year:", year.Int64())  // 2024
+}
+
+dayOfWeek := date.GetField(goda.DayOfWeekField)
+if dayOfWeek.Valid() {
+    fmt.Println("Day of week:", dayOfWeek.Int())  // 5 (Friday)
+}
 
+// Unsupported fields return unsupported TemporalValue
+hourOfDay := date.GetField(goda.HourOfDay)
+if hourOfDay.Unsupported() {
+    fmt.Println("Hour field is not supported for LocalDate")
+}
+
+// Time fields
 time := goda.MustNewLocalTime(14, 30, 45, 123456789)
-hour := time.GetFieldInt64(goda.HourOfDay)           // 14
-nanoOfDay := time.GetFieldInt64(goda.NanoOfDay)      // Total nanoseconds since midnight
-ampm := time.GetFieldInt64(goda.AmPmOfDay)           // 1 (PM)
+hour := time.GetField(goda.HourOfDay)
+if hour.Valid() {
+    fmt.Println("Hour:", hour.Int())  // 14
+}
+
+nanoOfDay := time.GetField(goda.NanoOfDay)
+if nanoOfDay.Valid() {
+    fmt.Println("Nanoseconds since midnight:", nanoOfDay.Int64())
+}
+```
+
+**TemporalValue API:**
+- `Valid() bool`: Returns true if the field is supported and no overflow occurred
+- `Unsupported() bool`: Returns true if the field is not supported by this temporal type
+- `Overflow() bool`: Returns true if the field value overflowed (reserved for future use)
+- `Int64() int64`: Get the raw value as int64
+- `Int() int`: Get the value as int (for convenience)
+
+**Why TemporalValue?**
+
+The `TemporalValue` return type provides type-safe field queries that prevent silent errors:
+- **Explicit validation**: Check `Valid()` before using the value
+- **Clear error semantics**: Distinguish between unsupported fields and actual errors
+- **Future-proof**: Ready for overflow detection when needed
+- **No silent zeros**: Unlike raw `int64` returns, you can distinguish between "0" and "unsupported"
+
+### TemporalAccessor Interface
+
+All temporal types implement the `TemporalAccessor` interface, providing a uniform query pattern:
+
+```go
+// TemporalAccessor provides read-only access to temporal fields
+type TemporalAccessor interface {
+    IsZero() bool
+    IsSupportedField(field Field) bool
+    GetField(field Field) TemporalValue
+}
+
+// Write generic functions that work with any temporal type
+func printYear(t goda.TemporalAccessor) {
+    if year := t.GetField(goda.YearField); year.Valid() {
+        fmt.Printf("Year: %d\n", year.Int())
+    }
+}
+
+// Works with LocalDate, LocalTime, or LocalDateTime
+printYear(goda.LocalDateNow())
+printYear(goda.LocalDateTimeNow())
 ```
 
 ### JSON Serialization
@@ -152,6 +212,8 @@ db.QueryRow("SELECT id, created_at, date FROM records WHERE id = ?", 1).Scan(
 | `Year` | Year | `2024` |
 | `DayOfWeek` | Day of week (1=Monday, 7=Sunday) | `Friday` |
 | `Field` | Date-time field enumeration | `HourOfDay`, `DayOfMonth` |
+| `TemporalAccessor` | Interface for querying temporal objects | Implemented by all temporal types |
+| `TemporalValue` | Type-safe field value with validation | Returned by `GetField()` |
 
 ### Time Formatting
 
@@ -176,7 +238,8 @@ Fractional seconds are automatically aligned to 3-digit boundaries (milliseconds
 
 ### Implemented Interfaces
 
-All types implement:
+All temporal types (`LocalDate`, `LocalTime`, `LocalDateTime`) implement:
+- `TemporalAccessor`: Universal query interface with `GetField(field Field) TemporalValue`
 - `fmt.Stringer`
 - `encoding.TextMarshaler` / `encoding.TextUnmarshaler`
 - `encoding.TextAppender` (zero-copy text marshaling)
@@ -191,7 +254,8 @@ This package follows the **ThreeTen/JSR-310** model (Java's `java.time` package)
 - **Type-safe**: Distinct types for date, time, and datetime
 - **Simple formats**: Uses ISO 8601 basic formats (not the full complex specification)
 - **Database-friendly**: Direct SQL integration
-- **Field-based access**: Universal field access pattern via `GetFieldInt64`
+- **Field-based access**: Universal field access pattern via `TemporalAccessor` interface
+- **Safe field queries**: `TemporalValue` return type validates field support and prevents silent errors
 - **Zero-value safe**: Zero values are properly handled throughout
 
 ### When to Use LocalDate, LocalTime, LocalDateTime

example_test.go

@@ -595,38 +595,222 @@ func ExampleLocalDateTime_IsSupportedField() {
 	// Supports OffsetSeconds: false
 }
 
-// ExampleLocalDate_GetFieldInt64 demonstrates getting field values from a date.
-func ExampleLocalDate_GetFieldInt64() {
+// ExampleLocalDate_GetField demonstrates querying date fields with TemporalValue.
+func ExampleLocalDate_GetField() {
 	date := goda.MustNewLocalDate(2024, goda.March, 15) // Friday
 
-	fmt.Printf("Year: %d\n", date.GetFieldInt64(goda.YearField))
-	fmt.Printf("Month: %d\n", date.GetFieldInt64(goda.MonthOfYear))
-	fmt.Printf("Day: %d\n", date.GetFieldInt64(goda.DayOfMonth))
-	fmt.Printf("Day of week: %d\n", date.GetFieldInt64(goda.DayOfWeekField))
-	fmt.Printf("Day of year: %d\n", date.GetFieldInt64(goda.DayOfYear))
+	// Query various date fields
+	dayOfWeek := date.GetField(goda.DayOfWeekField)
+	if dayOfWeek.Valid() {
+		fmt.Printf("Day of week: %d (1=Monday, 7=Sunday)\n", dayOfWeek.Int())
+	}
+
+	month := date.GetField(goda.MonthOfYear)
+	if month.Valid() {
+		fmt.Printf("Month: %d\n", month.Int())
+	}
+
+	year := date.GetField(goda.YearField)
+	if year.Valid() {
+		fmt.Printf("Year: %d\n", year.Int())
+	}
+
+	// Query unsupported field (time field on date)
+	hour := date.GetField(goda.HourOfDay)
+	if hour.Unsupported() {
+		fmt.Println("Hour field is not supported for LocalDate")
+	}
 
 	// Output:
-	// Year: 2024
+	// Day of week: 5 (1=Monday, 7=Sunday)
 	// Month: 3
-	// Day: 15
-	// Day of week: 5
+	// Year: 2024
+	// Hour field is not supported for LocalDate
+}
+
+// ExampleLocalDate_GetField_advancedFields demonstrates advanced date field queries.
+func ExampleLocalDate_GetField_advancedFields() {
+	date := goda.MustNewLocalDate(2024, goda.March, 15)
+
+	// Day of year (1-366)
+	dayOfYear := date.GetField(goda.DayOfYear)
+	fmt.Printf("Day of year: %d\n", dayOfYear.Int())
+
+	// Epoch days (days since 1970-01-01)
+	epochDay := date.GetField(goda.EpochDay)
+	fmt.Printf("Days since Unix epoch: %d\n", epochDay.Int64())
+
+	// Proleptic month (months since year 0)
+	prolepticMonth := date.GetField(goda.ProlepticMonth)
+	fmt.Printf("Proleptic month: %d\n", prolepticMonth.Int64())
+
+	// Era (0=BCE, 1=CE)
+	era := date.GetField(goda.Era)
+	if era.Int() == 1 {
+		fmt.Println("Era: CE (Common Era)")
+	}
+
+	// Output:
 	// Day of year: 75
+	// Days since Unix epoch: 19797
+	// Proleptic month: 24290
+	// Era: CE (Common Era)
 }
 
-// ExampleLocalTime_GetFieldInt64 demonstrates getting field values from a time.
-func ExampleLocalTime_GetFieldInt64() {
+// ExampleLocalTime_GetField demonstrates querying time fields with TemporalValue.
+func ExampleLocalTime_GetField() {
 	t := goda.MustNewLocalTime(14, 30, 45, 123456789)
 
-	fmt.Printf("Hour: %d\n", t.GetFieldInt64(goda.HourOfDay))
-	fmt.Printf("Minute: %d\n", t.GetFieldInt64(goda.MinuteOfHour))
-	fmt.Printf("Second: %d\n", t.GetFieldInt64(goda.SecondOfMinute))
-	fmt.Printf("Millisecond: %d\n", t.GetFieldInt64(goda.MilliOfSecond))
-	fmt.Printf("AM/PM: %d\n", t.GetFieldInt64(goda.AmPmOfDay))
+	// Query various time fields
+	hour := t.GetField(goda.HourOfDay)
+	if hour.Valid() {
+		fmt.Printf("Hour of day (0-23): %d\n", hour.Int())
+	}
+
+	minute := t.GetField(goda.MinuteOfHour)
+	if minute.Valid() {
+		fmt.Printf("Minute of hour: %d\n", minute.Int())
+	}
+
+	second := t.GetField(goda.SecondOfMinute)
+	if second.Valid() {
+		fmt.Printf("Second of minute: %d\n", second.Int())
+	}
+
+	nanos := t.GetField(goda.NanoOfSecond)
+	if nanos.Valid() {
+		fmt.Printf("Nanoseconds: %d\n", nanos.Int())
+	}
+
+	// Query unsupported field (date field on time)
+	dayOfMonth := t.GetField(goda.DayOfMonth)
+	if dayOfMonth.Unsupported() {
+		fmt.Println("DayOfMonth field is not supported for LocalTime")
+	}
 
 	// Output:
-	// Hour: 14
-	// Minute: 30
-	// Second: 45
-	// Millisecond: 123
-	// AM/PM: 1
+	// Hour of day (0-23): 14
+	// Minute of hour: 30
+	// Second of minute: 45
+	// Nanoseconds: 123456789
+	// DayOfMonth field is not supported for LocalTime
+}
+
+// ExampleLocalTime_GetField_clockHours demonstrates 12-hour clock field queries.
+func ExampleLocalTime_GetField_clockHours() {
+	// Afternoon time (2:30 PM)
+	afternoon := goda.MustNewLocalTime(14, 30, 0, 0)
+
+	// 24-hour format
+	hourOfDay := afternoon.GetField(goda.HourOfDay)
+	fmt.Printf("24-hour format: %d:30\n", hourOfDay.Int())
+
+	// 12-hour format components
+	hourOfAmPm := afternoon.GetField(goda.HourOfAmPm)
+	amPm := afternoon.GetField(goda.AmPmOfDay)
+	amPmStr := "AM"
+	if amPm.Int() == 1 {
+		amPmStr = "PM"
+	}
+	fmt.Printf("12-hour format: %d:30 %s\n", hourOfAmPm.Int(), amPmStr)
+
+	// Clock hour (1-12 instead of 0-11)
+	clockHour := afternoon.GetField(goda.ClockHourOfAmPm)
+	fmt.Printf("Clock hour (1-12): %d:30 %s\n", clockHour.Int(), amPmStr)
+
+	// Midnight special case
+	midnight := goda.MustNewLocalTime(0, 0, 0, 0)
+	midnightClock := midnight.GetField(goda.ClockHourOfDay)
+	fmt.Printf("Midnight clock hour: %d:00\n", midnightClock.Int())
+
+	// Output:
+	// 24-hour format: 14:30
+	// 12-hour format: 2:30 PM
+	// Clock hour (1-12): 2:30 PM
+	// Midnight clock hour: 24:00
+}
+
+// ExampleLocalTime_GetField_ofDayFields demonstrates querying cumulative daily values.
+func ExampleLocalTime_GetField_ofDayFields() {
+	t := goda.MustNewLocalTime(14, 30, 45, 500000000) // 2:30:45.5 PM
+
+	// Total seconds elapsed since midnight
+	secondOfDay := t.GetField(goda.SecondOfDay)
+	fmt.Printf("Seconds since midnight: %d\n", secondOfDay.Int())
+
+	// Total minutes elapsed since midnight
+	minuteOfDay := t.GetField(goda.MinuteOfDay)
+	fmt.Printf("Minutes since midnight: %d\n", minuteOfDay.Int())
+
+	// Total milliseconds elapsed since midnight
+	milliOfDay := t.GetField(goda.MilliOfDay)
+	fmt.Printf("Milliseconds since midnight: %d\n", milliOfDay.Int64())
+
+	// Total nanoseconds elapsed since midnight
+	nanoOfDay := t.GetField(goda.NanoOfDay)
+	fmt.Printf("Nanoseconds since midnight: %d\n", nanoOfDay.Int64())
+
+	// Output:
+	// Seconds since midnight: 52245
+	// Minutes since midnight: 870
+	// Milliseconds since midnight: 52245500
+	// Nanoseconds since midnight: 52245500000000
+}
+
+// ExampleLocalDateTime_GetField demonstrates querying fields from a date-time.
+func ExampleLocalDateTime_GetField() {
+	dt := goda.MustNewLocalDateTimeFromComponents(2024, goda.March, 15, 14, 30, 45, 123456789)
+
+	// Query date fields
+	year := dt.GetField(goda.YearField)
+	month := dt.GetField(goda.MonthOfYear)
+	day := dt.GetField(goda.DayOfMonth)
+
+	if year.Valid() && month.Valid() && day.Valid() {
+		fmt.Printf("Date: %04d-%02d-%02d\n", year.Int(), month.Int(), day.Int())
+	}
+
+	// Query time fields
+	hour := dt.GetField(goda.HourOfDay)
+	minute := dt.GetField(goda.MinuteOfHour)
+	second := dt.GetField(goda.SecondOfMinute)
+
+	if hour.Valid() && minute.Valid() && second.Valid() {
+		fmt.Printf("Time: %02d:%02d:%02d\n", hour.Int(), minute.Int(), second.Int())
+	}
+
+	// Query day of week
+	dayOfWeek := dt.GetField(goda.DayOfWeekField)
+	if dayOfWeek.Valid() {
+		fmt.Printf("Day of week: %d (Friday)\n", dayOfWeek.Int())
+	}
+
+	// Output:
+	// Date: 2024-03-15
+	// Time: 14:30:45
+	// Day of week: 5 (Friday)
+}
+
+// ExampleLocalDateTime_GetField_delegation demonstrates field delegation.
+func ExampleLocalDateTime_GetField_delegation() {
+	dt := goda.MustNewLocalDateTimeFromComponents(2024, goda.March, 15, 14, 30, 45, 0)
+
+	// LocalDateTime delegates date fields to LocalDate
+	dayOfYear := dt.GetField(goda.DayOfYear)
+	fmt.Printf("Day of year: %d\n", dayOfYear.Int())
+
+	// LocalDateTime delegates time fields to LocalTime
+	nanoOfDay := dt.GetField(goda.NanoOfDay)
+	fmt.Printf("Nanoseconds of day: %d\n", nanoOfDay.Int64())
+
+	// Unsupported fields return unsupported TemporalValue
+	offsetSeconds := dt.GetField(goda.OffsetSeconds)
+	if offsetSeconds.Unsupported() {
+		fmt.Println("OffsetSeconds is not supported for LocalDateTime")
+	}
+
+	// Output:
+	// Day of year: 75
+	// Nanoseconds of day: 52245000000000
+	// OffsetSeconds is not supported for LocalDateTime
 }