Improved Noda Time scalar type descriptions (#7665)

ChilliCream · Nov 5, 2024 · 2295bdd · 2295bdd
1 parent 97bab69
commit 2295bdd
Show file tree

Hide file tree

Showing 23 changed files with 945 additions and 64 deletions.
diff --git a/src/HotChocolate/Core/src/Types.NodaTime/BaseTypes/StringToStructBaseType.cs b/src/HotChocolate/Core/src/Types.NodaTime/BaseTypes/StringToStructBaseType.cs
@@ -1,5 +1,6 @@
 using System.Diagnostics.CodeAnalysis;
 using HotChocolate.Language;
+using NodaTime.Text;
 using static HotChocolate.Types.NodaTime.Properties.NodaTimeResources;
 
 namespace HotChocolate.Types.NodaTime;
@@ -133,4 +134,32 @@ public override bool TryDeserialize(object? resultValue, out object? runtimeValu
     protected abstract bool TryDeserialize(
         string resultValue,
         [NotNullWhen(true)] out TRuntimeType? runtimeValue);
+
+    protected string CreateDescription(
+        IPattern<TRuntimeType>[] allowedPatterns,
+        string description,
+        string extendedDescription)
+    {
+        if (allowedPatterns.All(PatternMap.ContainsKey))
+        {
+            var patternsText =
+                string.Join("\n", allowedPatterns.Select(p => $"- `{PatternMap[p]}`"));
+            var examplesText =
+                string.Join("\n", allowedPatterns.Select(e => $"- `{ExampleMap[e]}`"));
+
+            return string.Format(extendedDescription, patternsText, examplesText);
+        }
+
+        return description;
+    }
+
+    /// <summary>
+    /// A map from Noda Time patterns to more universal (ISO-like) formats for display purposes.
+    /// </summary>
+    protected abstract Dictionary<IPattern<TRuntimeType>, string> PatternMap { get; }
+
+    /// <summary>
+    /// A map from Noda Time patterns to example strings.
+    /// </summary>
+    protected abstract Dictionary<IPattern<TRuntimeType>, string> ExampleMap { get; }
 }
diff --git a/src/HotChocolate/Core/src/Types.NodaTime/DurationType.cs b/src/HotChocolate/Core/src/Types.NodaTime/DurationType.cs
@@ -25,7 +25,11 @@ public DurationType(params IPattern<Duration>[] allowedPatterns) : base("Duratio
 
         _allowedPatterns = allowedPatterns;
         _serializationPattern = allowedPatterns[0];
-        Description = NodaTimeResources.DurationType_Description;
+
+        Description = CreateDescription(
+            allowedPatterns,
+            NodaTimeResources.DurationType_Description,
+            NodaTimeResources.DurationType_Description_Extended);
     }
 
     /// <summary>
@@ -46,4 +50,16 @@ protected override bool TryDeserialize(
         string resultValue,
         [NotNullWhen(true)] out Duration? runtimeValue)
         => _allowedPatterns.TryParse(resultValue, out runtimeValue);
+
+    protected override Dictionary<IPattern<Duration>, string> PatternMap => new()
+    {
+        { DurationPattern.Roundtrip, "-D:hh:mm:ss.sssssssss" },
+        { DurationPattern.JsonRoundtrip, "-hh:mm:ss.sssssssss" }
+    };
+
+    protected override Dictionary<IPattern<Duration>, string> ExampleMap => new()
+    {
+        { DurationPattern.Roundtrip, "-1:20:00:00.999999999" },
+        { DurationPattern.JsonRoundtrip, "-44:00:00.999999999" }
+    };
 }
diff --git a/src/HotChocolate/Core/src/Types.NodaTime/InstantType.cs b/src/HotChocolate/Core/src/Types.NodaTime/InstantType.cs
@@ -25,7 +25,11 @@ public InstantType(params IPattern<Instant>[] allowedPatterns) : base("Instant")
 
         _allowedPatterns = allowedPatterns;
         _serializationPattern = allowedPatterns[0];
-        Description = NodaTimeResources.InstantType_Description;
+
+        Description = CreateDescription(
+            allowedPatterns,
+            NodaTimeResources.InstantType_Description,
+            NodaTimeResources.InstantType_Description_Extended);
     }
 
     /// <summary>
@@ -46,4 +50,16 @@ protected override bool TryDeserialize(
         string resultValue,
         [NotNullWhen(true)] out Instant? runtimeValue)
         => _allowedPatterns.TryParse(resultValue, out runtimeValue);
+
+    protected override Dictionary<IPattern<Instant>, string> PatternMap => new()
+    {
+        { InstantPattern.General, "YYYY-MM-DDThh:mm:ss±hh:mm" },
+        { InstantPattern.ExtendedIso, "YYYY-MM-DDThh:mm:ss.sssssssss±hh:mm" }
+    };
+
+    protected override Dictionary<IPattern<Instant>, string> ExampleMap => new()
+    {
+        { InstantPattern.General, "2000-01-01T20:00:00Z" },
+        { InstantPattern.ExtendedIso, "2000-01-01T20:00:00.999999999Z" }
+    };
 }
diff --git a/src/HotChocolate/Core/src/Types.NodaTime/LocalDateTimeType.cs b/src/HotChocolate/Core/src/Types.NodaTime/LocalDateTimeType.cs
@@ -25,7 +25,11 @@ public LocalDateTimeType(params IPattern<LocalDateTime>[] allowedPatterns) : bas
 
         _allowedPatterns = allowedPatterns;
         _serializationPattern = allowedPatterns[0];
-        Description = NodaTimeResources.LocalDateTimeType_Description;
+
+        Description = CreateDescription(
+            _allowedPatterns,
+            NodaTimeResources.LocalDateTimeType_Description,
+            NodaTimeResources.LocalDateTimeType_Description_Extended);
     }
 
     /// <summary>
@@ -46,4 +50,22 @@ protected override bool TryDeserialize(
         string resultValue,
         [NotNullWhen(true)] out LocalDateTime? runtimeValue)
         => _allowedPatterns.TryParse(resultValue, out runtimeValue);
+
+    protected override Dictionary<IPattern<LocalDateTime>, string> PatternMap => new()
+    {
+        { LocalDateTimePattern.GeneralIso, "YYYY-MM-DDThh:mm:ss" },
+        { LocalDateTimePattern.ExtendedIso, "YYYY-MM-DDThh:mm:ss.sssssssss" },
+        { LocalDateTimePattern.BclRoundtrip, "YYYY-MM-DDThh:mm:ss.sssssss" },
+        { LocalDateTimePattern.FullRoundtripWithoutCalendar, "YYYY-MM-DDThh:mm:ss.sssssssss" },
+        { LocalDateTimePattern.FullRoundtrip, "YYYY-MM-DDThh:mm:ss.sssssssss (calendar)" }
+    };
+
+    protected override Dictionary<IPattern<LocalDateTime>, string> ExampleMap => new()
+    {
+        { LocalDateTimePattern.GeneralIso, "2000-01-01T20:00:00" },
+        { LocalDateTimePattern.ExtendedIso, "2000-01-01T20:00:00.999" },
+        { LocalDateTimePattern.BclRoundtrip, "2000-01-01T20:00:00.9999999" },
+        { LocalDateTimePattern.FullRoundtripWithoutCalendar, "2000-01-01T20:00:00.999999999" },
+        { LocalDateTimePattern.FullRoundtrip, "2000-01-01T20:00:00.999999999 (ISO)" }
+    };
 }
diff --git a/src/HotChocolate/Core/src/Types.NodaTime/LocalDateType.cs b/src/HotChocolate/Core/src/Types.NodaTime/LocalDateType.cs
@@ -26,7 +26,11 @@ public LocalDateType(params IPattern<LocalDate>[] allowedPatterns) : base("Local
 
         _allowedPatterns = allowedPatterns;
         _serializationPattern = allowedPatterns[0];
-        Description = NodaTimeResources.LocalDateType_Description;
+
+        Description = CreateDescription(
+            allowedPatterns,
+            NodaTimeResources.LocalDateType_Description,
+            NodaTimeResources.LocalDateType_Description_Extended);
     }
 
     /// <summary>
@@ -47,4 +51,16 @@ protected override bool TryDeserialize(
         string resultValue,
         [NotNullWhen(true)] out LocalDate? runtimeValue)
         => _allowedPatterns.TryParse(resultValue, out runtimeValue);
+
+    protected override Dictionary<IPattern<LocalDate>, string> PatternMap => new()
+    {
+        { LocalDatePattern.Iso, "YYYY-MM-DD" },
+        { LocalDatePattern.FullRoundtrip, "YYYY-MM-DD (calendar)" }
+    };
+
+    protected override Dictionary<IPattern<LocalDate>, string> ExampleMap => new()
+    {
+        { LocalDatePattern.Iso, "2000-01-01" },
+        { LocalDatePattern.FullRoundtrip, "2000-01-01 (ISO)" }
+    };
 }
diff --git a/src/HotChocolate/Core/src/Types.NodaTime/LocalTimeType.cs b/src/HotChocolate/Core/src/Types.NodaTime/LocalTimeType.cs
@@ -26,7 +26,11 @@ public LocalTimeType(params IPattern<LocalTime>[] allowedPatterns) : base("Local
 
         _allowedPatterns = allowedPatterns;
         _serializationPattern = allowedPatterns[0];
-        Description = NodaTimeResources.LocalTimeType_Description;
+
+        Description = CreateDescription(
+            allowedPatterns,
+            NodaTimeResources.LocalTimeType_Description,
+            NodaTimeResources.LocalTimeType_Description_Extended);
     }
 
     /// <summary>
@@ -47,4 +51,18 @@ protected override bool TryDeserialize(
         string resultValue,
         [NotNullWhen(true)] out LocalTime? runtimeValue)
         => _allowedPatterns.TryParse(resultValue, out runtimeValue);
+
+    protected override Dictionary<IPattern<LocalTime>, string> PatternMap => new()
+    {
+        { LocalTimePattern.ExtendedIso, "hh:mm:ss.sssssssss" },
+        { LocalTimePattern.LongExtendedIso, "hh:mm:ss.sssssssss" },
+        { LocalTimePattern.GeneralIso, "hh:mm:ss" }
+    };
+
+    protected override Dictionary<IPattern<LocalTime>, string> ExampleMap => new()
+    {
+        { LocalTimePattern.ExtendedIso, "20:00:00.999" },
+        { LocalTimePattern.LongExtendedIso, "20:00:00.999999999" },
+        { LocalTimePattern.GeneralIso, "20:00:00" }
+    };
 }
diff --git a/src/HotChocolate/Core/src/Types.NodaTime/OffsetDateTimeType.cs b/src/HotChocolate/Core/src/Types.NodaTime/OffsetDateTimeType.cs
@@ -26,7 +26,11 @@ public OffsetDateTimeType(params IPattern<OffsetDateTime>[] allowedPatterns)
 
         _allowedPatterns = allowedPatterns;
         _serializationPattern = _allowedPatterns[0];
-        Description = NodaTimeResources.OffsetDateTimeType_Description;
+
+        Description = CreateDescription(
+            allowedPatterns,
+            NodaTimeResources.OffsetDateTimeType_Description,
+            NodaTimeResources.OffsetDateTimeType_Description_Extended);
     }
 
     /// <summary>
@@ -50,4 +54,20 @@ protected override bool TryDeserialize(
         string resultValue,
         [NotNullWhen(true)] out OffsetDateTime? runtimeValue)
         => _allowedPatterns.TryParse(resultValue, out runtimeValue);
+
+    protected override Dictionary<IPattern<OffsetDateTime>, string> PatternMap => new()
+    {
+        { OffsetDateTimePattern.GeneralIso, "YYYY-MM-DDThh:mm:ss±hh:mm" },
+        { OffsetDateTimePattern.ExtendedIso, "YYYY-MM-DDThh:mm:ss.sssssssss±hh:mm" },
+        { OffsetDateTimePattern.Rfc3339, "YYYY-MM-DDThh:mm:ss.sssssssss±hh:mm" },
+        { OffsetDateTimePattern.FullRoundtrip, "YYYY-MM-DDThh:mm:ss.sssssssss±hh:mm (calendar)" }
+    };
+
+    protected override Dictionary<IPattern<OffsetDateTime>, string> ExampleMap => new()
+    {
+        { OffsetDateTimePattern.GeneralIso, "2000-01-01T20:00:00Z" },
+        { OffsetDateTimePattern.ExtendedIso, "2000-01-01T20:00:00.999Z" },
+        { OffsetDateTimePattern.Rfc3339, "2000-01-01T20:00:00.999Z" },
+        { OffsetDateTimePattern.FullRoundtrip, "2000-01-01T20:00:00.999Z (ISO)" }
+    };
 }
diff --git a/src/HotChocolate/Core/src/Types.NodaTime/OffsetDateType.cs b/src/HotChocolate/Core/src/Types.NodaTime/OffsetDateType.cs
@@ -27,7 +27,11 @@ public OffsetDateType(params IPattern<OffsetDate>[] allowedPatterns) : base("Off
 
         _allowedPatterns = allowedPatterns;
         _serializationPattern = allowedPatterns[0];
-        Description = NodaTimeResources.OffsetDateType_Description;
+
+        Description = CreateDescription(
+            allowedPatterns,
+            NodaTimeResources.OffsetDateType_Description,
+            NodaTimeResources.OffsetDateType_Description_Extended);
     }
 
     /// <summary>
@@ -48,4 +52,16 @@ protected override bool TryDeserialize(
         string resultValue,
         [NotNullWhen(true)] out OffsetDate? runtimeValue)
         => _allowedPatterns.TryParse(resultValue, out runtimeValue);
+
+    protected override Dictionary<IPattern<OffsetDate>, string> PatternMap => new()
+    {
+        { OffsetDatePattern.GeneralIso, "YYYY-MM-DD±hh:mm" },
+        { OffsetDatePattern.FullRoundtrip, "YYYY-MM-DD±hh:mm (calendar)" }
+    };
+
+    protected override Dictionary<IPattern<OffsetDate>, string> ExampleMap => new()
+    {
+        { OffsetDatePattern.GeneralIso, "2000-01-01Z" },
+        { OffsetDatePattern.FullRoundtrip, "2000-01-01Z (ISO)" }
+    };
 }
diff --git a/src/HotChocolate/Core/src/Types.NodaTime/OffsetTimeType.cs b/src/HotChocolate/Core/src/Types.NodaTime/OffsetTimeType.cs
@@ -26,7 +26,11 @@ public OffsetTimeType(params IPattern<OffsetTime>[] allowedPatterns) : base("Off
 
         _allowedPatterns = allowedPatterns;
         _serializationPattern = _allowedPatterns[0];
-        Description = NodaTimeResources.OffsetTimeType_Description;
+
+        Description = CreateDescription(
+            allowedPatterns,
+            NodaTimeResources.OffsetTimeType_Description,
+            NodaTimeResources.OffsetTimeType_Description_Extended);
     }
 
     /// <summary>
@@ -47,4 +51,18 @@ protected override bool TryDeserialize(
         string resultValue,
         [NotNullWhen(true)] out OffsetTime? runtimeValue)
         => _allowedPatterns.TryParse(resultValue, out runtimeValue);
+
+    protected override Dictionary<IPattern<OffsetTime>, string> PatternMap => new()
+    {
+        { OffsetTimePattern.GeneralIso, "hh:mm:ss±hh:mm" },
+        { OffsetTimePattern.ExtendedIso, "hh:mm:ss.sssssssss±hh:mm" },
+        { OffsetTimePattern.Rfc3339, "hh:mm:ss.sssssssss±hh:mm" }
+    };
+
+    protected override Dictionary<IPattern<OffsetTime>, string> ExampleMap => new()
+    {
+        { OffsetTimePattern.GeneralIso, "20:00:00Z" },
+        { OffsetTimePattern.ExtendedIso, "20:00:00.999Z" },
+        { OffsetTimePattern.Rfc3339, "20:00:00.999999999Z" }
+    };
 }
diff --git a/src/HotChocolate/Core/src/Types.NodaTime/OffsetType.cs b/src/HotChocolate/Core/src/Types.NodaTime/OffsetType.cs
@@ -27,7 +27,11 @@ public OffsetType(params IPattern<Offset>[] allowedPatterns) : base("Offset")
 
         _allowedPatterns = allowedPatterns;
         _serializationPattern = allowedPatterns[0];
-        Description = NodaTimeResources.OffsetType_Description;
+
+        Description = CreateDescription(
+            allowedPatterns,
+            NodaTimeResources.OffsetType_Description,
+            NodaTimeResources.OffsetType_Description_Extended);
     }
 
     /// <summary>
@@ -48,4 +52,16 @@ protected override bool TryDeserialize(
         string resultValue,
         [NotNullWhen(true)] out Offset? runtimeValue)
         => _allowedPatterns.TryParse(resultValue, out runtimeValue);
+
+    protected override Dictionary<IPattern<Offset>, string> PatternMap => new()
+    {
+        { OffsetPattern.GeneralInvariant, "±hh:mm:ss" },
+        { OffsetPattern.GeneralInvariantWithZ, "Z" }
+    };
+
+    protected override Dictionary<IPattern<Offset>, string> ExampleMap => new()
+    {
+        { OffsetPattern.GeneralInvariant, "+02:30:00" },
+        { OffsetPattern.GeneralInvariantWithZ, "Z" }
+    };
 }