GraphQL Entity Naming Changes

src/Config/Entity.cs

@@ -26,7 +26,6 @@ public record Entity(
         object Source,
         [property: JsonPropertyName("rest")]
         object? Rest,
-        [property: JsonPropertyName("graphql")]
         object? GraphQL,
         [property: JsonPropertyName("permissions")]
         PermissionSetting[] Permissions,
@@ -37,6 +36,9 @@ public record Entity(
     {
         public const string JSON_PROPERTY_NAME = "entities";
 
+        [property: JsonPropertyName("graphql")]
+        public object? GraphQL { get; set; } = GraphQL;
+
         /// <summary>
         /// Gets the name of the underlying source database object.
         /// </summary>
@@ -58,6 +60,52 @@ DatabaseObjectSource objectSource
                 return objectSource.Name;
             }
         }
+
+        /// <summary>
+        /// Processes per entity GraphQL Naming Settings
+        /// Top Level: true | false
+        /// Alternatives: string, SingularPlural object
+        /// </summary>
+        public void ProcessGraphQLNamingConfig()
+        {
+            if (GraphQL is null)
+            {
+                return;
+            }
+
+            if (GraphQL is JsonElement configElement)
+            {
+                if (configElement.ValueKind is JsonValueKind.True || configElement.ValueKind is JsonValueKind.False)
+                {
+                    GraphQL = JsonSerializer.Deserialize<bool>(configElement)!;
+                }
+                else if (configElement.ValueKind is JsonValueKind.Object)
+                {
+                    JsonElement nameTypeSettings = configElement.GetProperty("type");
+                    object nameConfiguration;
+
+                    if (nameTypeSettings.ValueKind is JsonValueKind.String)
+                    {
+                        nameConfiguration = JsonSerializer.Deserialize<string>(nameTypeSettings)!;
+                    }
+                    else if (nameTypeSettings.ValueKind is JsonValueKind.Object)
+                    {
+                        nameConfiguration = JsonSerializer.Deserialize<SingularPlural>(nameTypeSettings)!;
+                    }
+                    else
+                    {
+                        throw new NotSupportedException("The runtime does not support this GraphQL settings type for an entity.");
+                    }
+
+                    GraphQLEntitySettings graphQLEntitySettings = new(Type: nameConfiguration);
+                    GraphQL = graphQLEntitySettings;
+                }
+            }
+            else
+            {
+                throw new NotSupportedException("The runtime does not support this GraphQL settings type for an entity.");
+            }
+        }
     }
 
     /// <summary>
@@ -90,7 +138,7 @@ public record RestEntitySettings(object Route);
     /// that will be used for this entity.Can be a string or Singular-Plural type.
     /// If string, a default plural route will be added as per the rules at
     /// <href="https://engdic.org/singular-and-plural-noun-rules-definitions-examples/" /></param>
-    public record GraphQLEntitySettings(object Type);
+    public record GraphQLEntitySettings([property: JsonPropertyName("type")] object? Type);
 
     /// <summary>
     /// Defines a name or route as singular (required) or
@@ -100,5 +148,7 @@ public record GraphQLEntitySettings(object Type);
     /// <param name="Plural">Optional pluralized form of the name.
     /// If plural is not specified, a default plural name will be used as per the rules at
     /// <href="https://engdic.org/singular-and-plural-noun-rules-definitions-examples/" /></param>
-    public record SingularPlural(string Singular, string Plural);
+    public record SingularPlural(
+            [property: JsonPropertyName("singular")] string Singular,
+            [property: JsonPropertyName("plural")] string Plural);
 }

src/Config/RuntimeConfig.cs

@@ -115,6 +115,17 @@ public void DetermineGlobalSettings()
             }
         }
 
+        /// <summary>
+        /// Deserialize GraphQL configuration on each entity.
+        /// </summary>
+        public void DetermineGraphQLEntityNames()
+        {
+            foreach (Entity entity in Entities.Values)
+            {
+                entity.ProcessGraphQLNamingConfig();
+            }
+        }
+
         /// <summary>
         /// Try to deserialize the given json string into its object form.
         /// </summary>

src/Service.GraphQLBuilder/Directives/ModelTypeDirective.cs

@@ -5,6 +5,7 @@ namespace Azure.DataApiBuilder.Service.GraphQLBuilder.Directives
     public class ModelDirectiveType : DirectiveType
     {
         public static string DirectiveName { get; } = "model";
+        public static string ModelNameArgument { get; } = "name";
 
         protected override void Configure(IDirectiveTypeDescriptor descriptor)
         {
@@ -13,7 +14,7 @@ protected override void Configure(IDirectiveTypeDescriptor descriptor)
 
             descriptor.Location(DirectiveLocation.Object);
 
-            descriptor.Argument("name")
+            descriptor.Argument(ModelNameArgument)
                 .Description("Underlying name of the database entity.")
                 .Type<StringType>();
         }

src/Service.GraphQLBuilder/GraphQLNaming.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics.CodeAnalysis;
 using System.Text.RegularExpressions;
 using Azure.DataApiBuilder.Config;
 using Azure.DataApiBuilder.Service.GraphQLBuilder.Directives;
@@ -9,22 +10,26 @@ namespace Azure.DataApiBuilder.Service.GraphQLBuilder
     public static class GraphQLNaming
     {
         // Name must start with an upper or lowercase letter
+        // Matches to this regular expression are names with valid prefix.
         private static readonly Regex _graphQLNameStart = new("^[a-zA-Z].*");
 
+        // Regex used to identify strings that do not have the defined GraphQL characters.
         // Letters, numbers and _ are only valid in names, so strip all that aren't.
         // Although we'll leave whitespace in so that downstream consumers can still
         // enforce their casing requirements
-        private static readonly Regex _graphQLValidSymbols = new("[^a-zA-Z0-9_\\s]");
+        private static readonly Regex _graphQLValidSymbols = new("[^a-zA-Z0-9_]");
 
         /// <summary>
         /// Enforces the GraphQL naming restrictions on <paramref name="name"/>.
+        /// Completely removes invalid characters from the input parameter: name.
+        /// Splits up the name into segments where *space* is the splitting token.
         /// </summary>
         /// <param name="name">String the enforce naming rules on</param>
         /// <seealso cref="https://spec.graphql.org/October2021/#Name"/>
-        /// <returns>A name that complies with the GraphQL name rules</returns>
-        private static string[] SanitizeGraphQLName(string name)
+        /// <returns>nameSegments, where each indice is a part of the name that complies with the GraphQL name rules.</returns>
+        public static string[] SanitizeGraphQLName(string name)
         {
-            if (!_graphQLNameStart.Match(name).Success)
+            if (ViolatesNamePrefixRequirements(name))
             {
                 // strip an illegal first character
                 name = name[1..];
@@ -36,23 +41,98 @@ private static string[] SanitizeGraphQLName(string name)
             return nameSegments;
         }
 
-        public static string FormatNameForObject(string name, Entity configEntity)
+        /// <summary>
+        /// Checks whether name has invalid characters at the start of the name provided.
+        /// - GraphQL specification requires that a name start with an upper or lowercase letter.
+        /// </summary>
+        /// <param name="name">Name to be checked.</param>
+        /// <seealso cref="https://spec.graphql.org/October2021/#Name"/>
+        /// <returns>True if the provided name violates requirements.</returns>
+        public static bool ViolatesNamePrefixRequirements(string name)
+        {
+            return !_graphQLNameStart.Match(name).Success;
+        }
+
+        /// <summary>
+        /// Checks whether name has invalid characters.
+        /// - GraphQL specification requires that a name does not contain anything other than
+        /// upper or lowercase letters or numbers.
+        /// </summary>
+        /// <param name="name">Name to be checked.</param>
+        /// <seealso cref="https://spec.graphql.org/October2021/#Name"/>
+        /// <returns>True if the provided name violates requirements.</returns>
+        public static bool ViolatesNameRequirements(string name)
+        {
+            return _graphQLValidSymbols.Match(name).Success;
+        }
+
+        /// <summary>
+        /// Attempts to deserialize and get the SingularPlural GraphQL naming config
+        /// of an Entity from the Runtime Configuration.
+        /// </summary>
+        public static string GetDefinedSingularName(string name, Entity configEntity)
         {
-            if (configEntity.GraphQL is SingularPlural namingRules)
+            if (TryGetConfiguredGraphQLName(configEntity, out string? graphQLName) &&
+                !string.IsNullOrEmpty(graphQLName))
             {
-                name = string.IsNullOrEmpty(namingRules.Singular) ? name : namingRules.Singular;
+                name = graphQLName;
+            }
+            else if (TryGetSingularPluralConfiguration(configEntity, out SingularPlural? singularPluralConfig) &&
+                !string.IsNullOrEmpty(singularPluralConfig.Singular))
+            {
+                name = singularPluralConfig.Singular;
             }
 
-            string[] nameSegments = SanitizeGraphQLName(name);
+            return name;
+        }
+
+        /// <summary>
+        /// Attempts to deserialize and get the SingularPlural GraphQL naming config
+        /// of an Entity from the Runtime Configuration.
+        /// </summary>
+        /// <param name="configEntity">Entity to fetch GraphQL naming, if set.</param>
+        /// <param name="singularPluralConfig">Entity's configured GraphQL singular/plural naming.</param>
+        /// <returns>True if configuration found, false otherwise.</returns>
+        public static bool TryGetSingularPluralConfiguration(Entity configEntity, [NotNullWhen(true)] out SingularPlural? singularPluralConfig)
+        {
+            if (configEntity.GraphQL is not null && configEntity.GraphQL is GraphQLEntitySettings graphQLEntitySettings)
+            {
+                if (graphQLEntitySettings is not null && graphQLEntitySettings.Type is SingularPlural singularPlural)
+                {
+                    if (singularPlural is not null)
+                    {
+                        singularPluralConfig = singularPlural;
+                        return true;
+                    }
+                }
+            }
 
-            return string.Join("", nameSegments.Select(n => $"{char.ToUpperInvariant(n[0])}{n[1..]}"));
+            singularPluralConfig = null;
+            return false;
         }
 
-        public static string FormatNameForObject(NameNode name, Entity configEntity)
+        public static bool TryGetConfiguredGraphQLName(Entity configEntity, [NotNullWhen(true)] out string? graphQLName)
         {
-            return FormatNameForObject(name.Value, configEntity);
+            if (configEntity.GraphQL is not null && configEntity.GraphQL is GraphQLEntitySettings graphQLEntitySettings)
+            {
+                if (graphQLEntitySettings is not null && graphQLEntitySettings.Type is string typeEntityName)
+                {
+                    graphQLName = typeEntityName;
+                    return true;
+                }
+            }
+
+            graphQLName = null;
+            return false;
         }
 
+        /// <summary>
+        /// Format fields generated by the runtime aligning with
+        /// GraphQL best practices.
+        /// </summary>
+        /// <param name="name"></param>
+        /// <seealso cref="https://github.com/hendrikniemann/graphql-style-guide#fields"/>
+        /// <returns></returns>
         public static string FormatNameForField(string name)
         {
             string[] nameSegments = SanitizeGraphQLName(name);
@@ -65,26 +145,49 @@ public static string FormatNameForField(NameNode name)
             return FormatNameForField(name.Value);
         }
 
+        /// <summary>
+        /// Helper to pluralize the value of a NameNode HotChocolate schema object
+        /// </summary>
+        /// <param name="name">HotChocolate schema object type NameNode</param>
+        /// <param name="configEntity">Entity definition from runtime configuration.</param>
+        /// <returns></returns>
         public static NameNode Pluralize(NameNode name, Entity configEntity)
         {
             return Pluralize(name.Value, configEntity);
         }
 
+        /// <summary>
+        /// Helper to pluralize the passed in string with the plural name defined
+        /// for the entity in the runtime configuration.
+        /// If the plural name is not defined, use the singularName.Pluralize() value
+        /// and if that does not exist, use the top-level entity name value, pluralized.
+        /// </summary>
+        /// <param name="name">string representing a name to pluralize</param>
+        /// <param name="configEntity">Entity definition from runtime configuration.</param>
+        /// <returns></returns>
         public static NameNode Pluralize(string name, Entity configEntity)
         {
-            if (configEntity.GraphQL is SingularPlural namingRules)
+            if (TryGetConfiguredGraphQLName(configEntity, out string? graphQLName) &&
+                !string.IsNullOrEmpty(graphQLName))
             {
-                if (!string.IsNullOrEmpty(namingRules.Plural))
-                {
-                    return new NameNode(namingRules.Plural);
-                }
-
-                name = string.IsNullOrEmpty(namingRules.Singular) ? name : namingRules.Singular;
+                return new NameNode(graphQLName.Pluralize());
+            }
+            else if (TryGetSingularPluralConfiguration(configEntity, out SingularPlural? namingRules) &&
+                !string.IsNullOrEmpty(namingRules.Plural))
+            {
+                return new NameNode(namingRules.Plural);
             }
 
-            return new NameNode(FormatNameForField(name).Pluralize());
+            return new NameNode(name.Pluralize());
         }
 
+        /// <summary>
+        /// Given an object type definition i.e. type EntityName @model(name:TopLevelEntityName)
+        /// Get the value assigned to the model directive which is the top-level entity name.
+        /// If no model directive exists, the name set on the object type definition is returned.
+        /// </summary>
+        /// <param name="node">Object type definition</param>
+        /// <returns>string representing the top-level entity name defined in runtime configuration.</returns>
         public static string ObjectTypeToEntityName(ObjectTypeDefinitionNode node)
         {
             DirectiveNode modelDirective = node.Directives.First(d => d.Name.Value == ModelDirectiveType.DirectiveName);

src/Service.GraphQLBuilder/GraphQLUtils.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics.CodeAnalysis;
 using Azure.DataApiBuilder.Config;
 using Azure.DataApiBuilder.Service.Exceptions;
 using Azure.DataApiBuilder.Service.GraphQLBuilder.Directives;
@@ -160,5 +161,48 @@ public static bool CreateAuthorizationDirectiveIfNecessary(
                 return false;
             }
         }
+
+        /// <summary>
+        /// Get the model name (EntityName) defined on the object type definition.
+        /// </summary>
+        /// <param name="fieldDirectives">Collection of directives on GraphQL field.</param>
+        /// <param name="modelName">Value of @model directive, if present.</param>
+        /// <returns></returns>
+        public static bool TryExtractGraphQLFieldModelName(IDirectiveCollection fieldDirectives, [NotNullWhen(true)] out string? modelName)
+        {
+            foreach (Directive dir in fieldDirectives)
+            {
+                if (dir.Name.Value == ModelDirectiveType.DirectiveName)
+                {
+                    dir.ToObject<ModelDirectiveType>();
+                    modelName = dir.GetArgument<string>(ModelDirectiveType.ModelNameArgument).ToString();
+
+                    return modelName is not null;
+                }
+            }
+
+            modelName = null;
+            return false;
+        }
+
+        /// <summary>
+        /// UnderlyingGraphQLEntityType is the main GraphQL type that is described by
+        /// this type. This strips all modifiers, such as List and Non-Null.
+        /// So the following GraphQL types would all have the underlyingType Book:
+        /// - Book
+        /// - [Book]
+        /// - Book!
+        /// - [Book]!
+        /// - [Book!]!
+        /// </summary>
+        public static ObjectType UnderlyingGraphQLEntityType(IType type)
+        {
+            if (type is ObjectType underlyingType)
+            {
+                return underlyingType;
+            }
+
+            return UnderlyingGraphQLEntityType(type.InnerType());
+        }
     }
 }