fix(parser)!: read date values without an offset as utc, with DateTimeKindForValuesWithoutOffset

[pdevito3]

Summary

A DateTime or DateTimeOffset filter value without an offset is now UTC by default. The new setting DateTimeKindForValuesWithoutOffset (default DateTimeKind.Utc) selects a different kind.

 ParseFilter(input, config)
+  kind = config.DateTimeKindForValuesWithoutOffset   // Utc by default
   DateTime value without an offset
-    scalar: Local (AssumeLocal)
-    list and custom operation: a different rule (AdjustToUniversal only)
+    every path (scalar, quoted, ^^ [...] list, custom operation): kind
   DateTime value with an offset
+    converted to the UTC time, then given the kind
   DateTimeOffset value without an offset
-    the offset of the server
+    UTC, or the offset of the server when kind is Local

DateTimeKindForValuesWithoutOffset	2024-01-15T08:00:00 becomes	Use it for
Utc (default)	08:00, Kind=Utc	timestamp with time zone (timestamptz) on Npgsql, and most APIs
Unspecified	08:00, Kind=Unspecified	timestamp without time zone on Npgsql
Local	08:00 in the server time zone, Kind=Local	the v1.14.2 scalar behavior

The setting is on QueryKitSettings, QueryKitConfiguration, and IQueryKitFilterBehavior (a default interface member that returns Utc, so existing implementers still compile). The parser sets it for one parse on the current thread and restores it after the parse.

Breaking change

Npgsql needs a Utc DateTime for a timestamptz column. It rejects a Utc DateTime for a timestamp without time zone column.

• timestamptz columns: a filter value without an offset threw on Postgres in v1.14.2. Now it works. No action is necessary.
• timestamp without time zone columns: a filter value without an offset now throws "'timestamp without time zone' literal cannot be generated for a UTC DateTime". To correct this, set the kind to Unspecified:

var config = new QueryKitConfiguration(settings =>
{
    settings.DateTimeKindForValuesWithoutOffset = DateTimeKind.Unspecified;
});

• To keep the v1.14.2 time zone rule (the server time zone), set the kind to Local.
• The setting is global for one filter. One filter cannot compare a timestamptz column and a timestamp without time zone column on Npgsql.

The README has a new section, "Date and Time Values Without an Offset".

Evidence

verify-querykit harness, Postgres, machine time zone EET (UTC+2). CreatedAt is timestamptz. LocalCreatedAt is timestamp without time zone. Pancakes has 2024-01-15 08:00.

Filter	Config	v2 before	This PR
CreatedAt == "2024-01-15T08:00:00"	default, literal and parameterized	ArgumentException: "a UTC DateTime is required"	Pancakes
CreatedAt ^^ [2024-01-15T08:00:00]	default, literal and parameterized	ArgumentException: "a UTC DateTime is required"	Pancakes
LocalCreatedAt == "2024-01-15T08:00:00"	default	Pancakes	throws (see Breaking change)
LocalCreatedAt == "2024-01-15T08:00:00"	unspecified-datetime, literal and parameterized	not available	Pancakes, TIMESTAMP '2024-01-15T08:00:00'
LocalCreatedAt ^^ [2024-01-15T10:00:00+02:00]	unspecified-datetime	not available	Pancakes

Tests:

• Unit, DateTimeKindForValuesWithoutOffsetTests: the Utc, Unspecified, and Local kinds for the scalar, quoted, list, quoted-list, and custom operation forms, with and without parameters. Also values with an offset, DateTimeOffset, the restore after the parse, and an interface implementer without the setting.
• Integration, Postgres (Testcontainers):
  • timestamptz_value_without_offset_is_utc_by_default: 24 cases on SpecificDateTime and SpecificDate.
  • timestamp_without_time_zone_value_matches_with_unspecified_kind: 12 cases on the new LocalDateTime column (migration AddPersonLocalDateTime).
• dotnet test after the rebase on v2: 564 unit tests and 357 integration tests pass. The build with -warnaserror has 0 warnings. A nullable warning from fix(filter)!: resolve query names in the grammar again #154 in AliasCultureTests is corrected here.

Merge Danger

Door: two-way

The change is code only. The new test column is in the test web project, not in the library.

Blast Radius: consumers

Each consumer that filters a timestamp without time zone column on Npgsql with a value without an offset must set Unspecified. On a server that is not on UTC, a consumer that depended on the server time zone gets different rows. That consumer must set Local.