🔌 Shared Semantic Values

SwifQL now has shared semantic values for database-facing civil dates, times, civil date-times, and structural intervals: PureDate, PureTime, DateTime, and Interval.

let date = PureDate(year: 2026, month: 9, day: 4)!
let time = PureTime(
    hour: 12,
    minute: 34,
    second: 56,
    nanosecond: 123_456_789
)!
let dateTime = DateTime(
    year: 2026,
    month: 9,
    day: 4,
    hour: 12,
    minute: 34,
    second: 56,
    nanosecond: 123_456_789
)!
let interval = Interval(
    months: 2,
    days: -3,
    microseconds: 4
)

SwifQL
    .select(date, time, dateTime, interval)
    .prepare(.psql)
    .plain

will give:

SELECT DATE '2026-09-04', TIME '12:34:56.123456789', TIMESTAMP '2026-09-04 12:34:56.123456789', INTERVAL '2 months -3 days 4 microseconds'

Shared semantic values

PureDate is a timezone-free proleptic-Gregorian civil date. It supports astronomical years, including year zero and extended years, together with explicit positive and negative infinity states.

PureTime is a nanosecond-capable time of day, not an elapsed duration. Its domain includes the distinct 24:00:00 endpoint.

DateTime combines a civil date and time without introducing timezone or instant semantics. Exact 24:00:00 input canonicalizes to the following day's midnight.

Interval preserves independent signed months, days, and microseconds. It is structural rather than a flattened duration and intentionally does not conform to Comparable.

PureDate and DateTime can bridge to Foundation.Date with an explicit Gregorian Calendar and TimeZone. That conversion is exact and failable rather than silently normalizing unsupported values.

Binding and schema inference

All four values use the ordinary SwifQL value/binding pipeline, so prepared queries keep the original Swift values and their traversal order.

Automatic inference remains intentionally conservative:

PureDate        -> .date
PureTime        -> .time
Foundation.Date -> .timestamptz
DateTime        -> .text
Interval        -> .text

Use explicit .timestamp or .interval schema types when those contracts are intended for DateTime or Interval.

Dialect behavior

PostgreSQL renders the shared values as native DATE, TIME, TIMESTAMP, and INTERVAL expressions while preserving their civil semantics.

Duck uses its exact supported forms, including TIME_NS and TIMESTAMP_NS for nanosecond lexical precision. Positive extended dates adapt only their parser spelling, while the Swift value keeps its canonical identity. TIMESTAMP_NS still has a finite physical range, and shared interval infinity is not advertised as native Duck interval infinity.

MySQL follows an exact-or-hard-fail policy. Supported finite dates and date-times render as DATE / DATETIME, and time fractions must be exactly representable at MySQL microsecond precision. Unsupported years, special states, or non-microsecond nanoseconds are not silently rounded or coerced.

Compatibility

This release is additive. Existing SwifQL query source does not need to migrate to use the existing APIs.