refactor: model Solace integer-or-schema values as a type hierarchy

SolaceIntegerOrSchema is now an abstract base with SolaceInteger and
SolaceIntegerSchema subtypes, matching the MQTT union types. Callers use
type checks instead of null-checking Integer and Schema, and an empty
value can no longer be constructed, so Validate() is gone. Implicit
conversions from long and AsyncApiJsonSchema keep assignments such as
Priority = 7 compiling.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: bielu

src/ByteBard.AsyncAPI.Bindings/Solace/SolaceIntegerOrSchema.cs

@@ -3,81 +3,85 @@ namespace ByteBard.AsyncAPI.Bindings.Solace
     using System;
     using ByteBard.AsyncAPI.Models;
     using ByteBard.AsyncAPI.Models.Interfaces;
+    using ByteBard.AsyncAPI.Readers;
+    using ByteBard.AsyncAPI.Readers.ParseNodes;
     using ByteBard.AsyncAPI.Writers;
 
-    /// <summary>Represents a Solace integer, JSON Schema object, or JSON Schema reference.</summary>
-    public class SolaceIntegerOrSchema : IAsyncApiSerializable
+    /// <summary>
+    /// A Solace value represented by either an integer (<see cref="SolaceInteger"/>) or a JSON Schema or schema reference (<see cref="SolaceIntegerSchema"/>).
+    /// </summary>
+    /// <remarks>Integers and schemas convert implicitly, so <c>binding.Priority = 7;</c> works.</remarks>
+    public abstract class SolaceIntegerOrSchema : IAsyncApiSerializable
     {
-        private long? integer;
-        private AsyncApiJsonSchema schema;
-
-        public long? Integer
+        private protected SolaceIntegerOrSchema()
         {
-            get => this.integer;
-            set
-            {
-                this.integer = value;
-                if (value.HasValue) this.schema = null;
-            }
         }
 
-        public AsyncApiJsonSchema Schema
-        {
-            get => this.schema;
-            set
-            {
-                this.schema = value;
-                if (value != null) this.integer = null;
-            }
-        }
+        public static implicit operator SolaceIntegerOrSchema(long value) => new SolaceInteger(value);
+
+        public static implicit operator SolaceIntegerOrSchema(AsyncApiJsonSchema schema) => schema == null ? null : new SolaceIntegerSchema(schema);
 
         /// <summary>
-        /// Writes the integer or schema value directly for AsyncAPI 2.0, after validating that a value is present.
+        /// Parses a scalar as a signed 64-bit integer, or an object as a schema or schema reference.
         /// </summary>
-        /// <exception cref="ArgumentNullException"><paramref name="writer"/> is null.</exception>
-        /// <exception cref="InvalidOperationException">Neither an integer nor a schema is set.</exception>
-        public void SerializeV2(IAsyncApiWriter writer) => this.Serialize(writer, false);
+        /// <returns>A <see cref="SolaceInteger"/> or <see cref="SolaceIntegerSchema"/>.</returns>
+        /// <remarks>Schema field errors handled by the reader are recorded as diagnostics. Scalar parsing errors propagate to the caller.</remarks>
+        /// <exception cref="ByteBard.AsyncAPI.Readers.Exceptions.AsyncApiReaderException">The scalar cannot be parsed as an Int64, or a non-scalar node is not a schema object.</exception>
+        /// <exception cref="ByteBard.AsyncAPI.Exceptions.AsyncApiException">A schema reference has a non-scalar $ref value.</exception>
+        public static SolaceIntegerOrSchema Parse(ParseNode node)
+        {
+            return node is ValueNode
+                ? new SolaceInteger(node.GetLongValue())
+                : new SolaceIntegerSchema(AsyncApiJsonSchemaDeserializer.LoadSchema(node));
+        }
+
         /// <summary>
-        /// Writes the integer or schema value directly for AsyncAPI 3.0, after validating that a value is present.
+        /// Writes the integer or schema value directly for AsyncAPI 2.0, without a property name or wrapper object.
         /// </summary>
-        /// <exception cref="ArgumentNullException"><paramref name="writer"/> is null.</exception>
-        /// <exception cref="InvalidOperationException">Neither an integer nor a schema is set.</exception>
-        public void SerializeV3(IAsyncApiWriter writer) => this.Serialize(writer, true);
+        public abstract void SerializeV2(IAsyncApiWriter writer);
 
         /// <summary>
-        /// Checks that an integer or schema is present, without validating its range or schema contents.
+        /// Writes the integer or schema value directly for AsyncAPI 3.0, without a property name or wrapper object.
         /// </summary>
-        /// <exception cref="InvalidOperationException">Neither an integer nor a schema is set.</exception>
-        public void Validate()
+        public abstract void SerializeV3(IAsyncApiWriter writer);
+    }
+
+    /// <summary>The integer alternative of <see cref="SolaceIntegerOrSchema"/>.</summary>
+    public sealed class SolaceInteger : SolaceIntegerOrSchema
+    {
+        public SolaceInteger(long value)
         {
-            if (!this.Integer.HasValue && this.Schema == null)
-            {
-                throw new InvalidOperationException("A Solace integer-or-schema value must contain an integer or a schema.");
-            }
+            this.Value = value;
         }
 
+        public long Value { get; }
+
+        /// <exception cref="ArgumentNullException"><paramref name="value"/> is null.</exception>
+        public static implicit operator long(SolaceInteger value) => (value ?? throw new ArgumentNullException(nameof(value))).Value;
+
+        public override void SerializeV2(IAsyncApiWriter writer) => writer.WriteValue(this.Value);
+
+        public override void SerializeV3(IAsyncApiWriter writer) => writer.WriteValue(this.Value);
+    }
+
+    /// <summary>The schema alternative of <see cref="SolaceIntegerOrSchema"/>.</summary>
+    public sealed class SolaceIntegerSchema : SolaceIntegerOrSchema
+    {
         /// <summary>
-        /// Validates and writes the integer or schema value without a property name or wrapper object.
+        /// Retains the supplied schema or reference without copying it.
         /// </summary>
-        /// <param name="writer">The writer receiving the value.</param>
-        /// <param name="v3">Uses AsyncAPI 3.0 schema serialization when true and AsyncAPI 2.0 when false.</param>
-        /// <exception cref="ArgumentNullException"><paramref name="writer"/> is null.</exception>
-        /// <exception cref="InvalidOperationException">Neither an integer nor a schema is set.</exception>
-        private void Serialize(IAsyncApiWriter writer, bool v3)
+        /// <exception cref="ArgumentNullException"><paramref name="schema"/> is null.</exception>
+        public SolaceIntegerSchema(AsyncApiJsonSchema schema)
         {
-            if (writer is null) throw new ArgumentNullException(nameof(writer));
-            this.Validate();
-            if (this.Integer.HasValue)
-            {
-                writer.WriteValue(this.Integer.Value);
-                return;
-            }
-
-            if (this.Schema != null)
-            {
-                if (v3) this.Schema.SerializeV3(writer);
-                else this.Schema.SerializeV2(writer);
-            }
+            this.Schema = schema ?? throw new ArgumentNullException(nameof(schema));
         }
+
+        public AsyncApiJsonSchema Schema { get; }
+
+        public static implicit operator AsyncApiJsonSchema(SolaceIntegerSchema value) => value?.Schema;
+
+        public override void SerializeV2(IAsyncApiWriter writer) => this.Schema.SerializeV2(writer);
+
+        public override void SerializeV3(IAsyncApiWriter writer) => this.Schema.SerializeV3(writer);
     }
 }

src/ByteBard.AsyncAPI.Bindings/Solace/SolaceOperationBinding.cs

@@ -20,61 +20,38 @@ public class SolaceOperationBinding : OperationBinding<SolaceOperationBinding>
         {
             { "bindingVersion", (a, n) => a.BindingVersion = n.GetScalarValue() },
             { "destinations", (a, n) => a.Destinations = n.CreateList(s => s.ParseMap(SolaceDestination.Fields)) },
-            { "timeToLive", (a, n) => a.TimeToLive = ReadIntegerOrSchema(n) },
-            { "priority", (a, n) => a.Priority = ReadIntegerOrSchema(n) },
+            { "timeToLive", (a, n) => a.TimeToLive = SolaceIntegerOrSchema.Parse(n) },
+            { "priority", (a, n) => a.Priority = SolaceIntegerOrSchema.Parse(n) },
             { "dmqEligible", (a, n) => a.DmqEligible = n.GetBooleanValue() },
         };
 
-        /// <summary>
-        /// Parses a scalar as a signed 64-bit integer, or an object as a schema or schema reference.
-        /// </summary>
-        /// <returns>A value containing the parsed integer or schema.</returns>
-        /// <remarks>Schema field errors handled by the reader are recorded as diagnostics. Scalar parsing errors propagate to the caller.</remarks>
-        /// <exception cref="ByteBard.AsyncAPI.Readers.Exceptions.AsyncApiReaderException">The scalar cannot be parsed as an Int64, or a non-scalar node is not a schema object.</exception>
-        /// <exception cref="ByteBard.AsyncAPI.Exceptions.AsyncApiException">A schema reference has a non-scalar $ref value.</exception>
-        internal static SolaceIntegerOrSchema ReadIntegerOrSchema(ParseNode node)
-        {
-            if (node is ValueNode)
-            {
-                return new SolaceIntegerOrSchema { Integer = node.GetLongValue() };
-            }
-
-            return new SolaceIntegerOrSchema { Schema = AsyncApiJsonSchemaDeserializer.LoadSchema(node) };
-        }
-
         /// <summary>
         /// Writes the Solace operation binding object and its extensions for AsyncAPI 2.0.
         /// </summary>
         /// <exception cref="ArgumentNullException"><paramref name="writer"/> is null.</exception>
-        /// <exception cref="InvalidOperationException">TimeToLive or Priority is present but contains neither an integer nor a schema.</exception>
         public override void SerializeV2(IAsyncApiWriter writer) => Serialize(writer, false);
         /// <summary>
         /// Writes the Solace operation binding object and its extensions for AsyncAPI 3.0.
         /// </summary>
         /// <exception cref="ArgumentNullException"><paramref name="writer"/> is null.</exception>
-        /// <exception cref="InvalidOperationException">TimeToLive or Priority is present but contains neither an integer nor a schema.</exception>
         public override void SerializeV3(IAsyncApiWriter writer) => Serialize(writer, true);
 
         /// <summary>
         /// Writes the Solace operation binding object and its extensions for AsyncAPI 2.0.
         /// </summary>
-        /// <remarks>Validates the optional integer-or-schema values before writing the binding. Explicit false DmqEligible values are preserved.</remarks>
+        /// <remarks>Explicit false DmqEligible values are preserved.</remarks>
         /// <exception cref="ArgumentNullException"><paramref name="writer"/> is null.</exception>
-        /// <exception cref="InvalidOperationException">TimeToLive or Priority is present but contains neither an integer nor a schema.</exception>
         public override void SerializeProperties(IAsyncApiWriter writer) => Serialize(writer, false);
 
         /// <summary>
-        /// Validates the optional integer-or-schema values, then writes the binding object and its extensions.
+        /// Writes the binding object and its extensions.
         /// </summary>
         /// <param name="writer">The writer receiving the value.</param>
         /// <param name="v3">Uses AsyncAPI 3.0 schema serialization when true and AsyncAPI 2.0 when false.</param>
         /// <exception cref="ArgumentNullException"><paramref name="writer"/> is null.</exception>
-        /// <exception cref="InvalidOperationException">TimeToLive or Priority is present but contains neither an integer nor a schema.</exception>
         private void Serialize(IAsyncApiWriter writer, bool v3)
         {
             if (writer is null) throw new ArgumentNullException(nameof(writer));
-            this.TimeToLive?.Validate();
-            this.Priority?.Validate();
             writer.WriteStartObject();
             writer.WriteOptionalCollection("destinations", this.Destinations, (w, d) => d.Serialize(w));
             writer.WriteOptionalObject("timeToLive", this.TimeToLive, (w, value) => { if (v3) value.SerializeV3(w); else value.SerializeV2(w); });

test/ByteBard.AsyncAPI.Tests/Bindings/Solace/SolaceBindings_Should.cs

@@ -20,8 +20,8 @@ public void OperationBinding_RoundTripsNestedDestinationsAndScalarUnionValues(As
             operation.Bindings.Add(new SolaceOperationBinding
             {
                 DmqEligible = false,
-                TimeToLive = new SolaceIntegerOrSchema { Integer = 0 },
-                Priority = new SolaceIntegerOrSchema { Integer = 7 },
+                TimeToLive = 0,
+                Priority = 7,
                 Destinations =
                 {
                     new SolaceDestination
@@ -60,14 +60,8 @@ public void OperationBinding_RoundTripsSchemaAndReferenceUnionValues(AsyncApiVer
             };
             operation.Bindings.Add(new SolaceOperationBinding
             {
-                TimeToLive = new SolaceIntegerOrSchema
-                {
-                    Schema = new AsyncApiJsonSchema { Description = "ttl schema" },
-                },
-                Priority = new SolaceIntegerOrSchema
-                {
-                    Schema = new AsyncApiJsonSchemaReference("#/components/schemas/Priority"),
-                },
+                TimeToLive = new AsyncApiJsonSchema { Description = "ttl schema" },
+                Priority = new AsyncApiJsonSchemaReference("#/components/schemas/Priority"),
             });
 
             var document = new AsyncApiDocument
@@ -96,8 +90,8 @@ public void OperationBinding_RoundTripsSchemaAndReferenceUnionValues(AsyncApiVer
             diagnostics.Errors.Should().BeEmpty();
             var binding = reparsed.Operations.Values.Should().ContainSingle().Which.Bindings.Values.Should()
                 .ContainSingle().Which.Should().BeOfType<SolaceOperationBinding>().Subject;
-            binding.TimeToLive.Schema.Description.Should().Be("ttl schema");
-            ((AsyncApiJsonSchemaReference)binding.Priority.Schema).Reference.Reference.Should().Be("#/components/schemas/Priority");
+            binding.TimeToLive.Should().BeOfType<SolaceIntegerSchema>().Which.Schema.Description.Should().Be("ttl schema");
+            binding.Priority.Should().BeOfType<SolaceIntegerSchema>().Which.Schema.Should().BeOfType<AsyncApiJsonSchemaReference>().Which.Reference.Reference.Should().Be("#/components/schemas/Priority");
         }
 
         [TestCase(AsyncApiVersion.AsyncApi2_0)]
@@ -108,7 +102,7 @@ public void OperationBinding_RoundTripsLargeTimeToLive(AsyncApiVersion version)
             var operation = new AsyncApiOperation();
             operation.Bindings.Add(new SolaceOperationBinding
             {
-                TimeToLive = new SolaceIntegerOrSchema { Integer = largeTtl },
+                TimeToLive = largeTtl,
             });
 
             var yaml = operation.SerializeAsYaml(version);
@@ -118,22 +112,20 @@ public void OperationBinding_RoundTripsLargeTimeToLive(AsyncApiVersion version)
             settings.Bindings = new List<IBindingParser<IBinding>> { new SolaceOperationBinding() };
             var parsed = new AsyncApiStringReader(settings).ReadFragment<AsyncApiOperation>(yaml, version, out _);
             var binding = parsed.Bindings.Should().ContainSingle().Which.Value.Should().BeOfType<SolaceOperationBinding>().Subject;
-            binding.TimeToLive.Integer.Should().Be(largeTtl);
+            binding.TimeToLive.Should().BeOfType<SolaceInteger>().Which.Value.Should().Be(largeTtl);
         }
 
         [Test]
-        public void OperationBinding_RejectsEmptyIntegerOrSchemaBeforeWriting()
+        public void IntegerOrSchema_ConvertsImplicitlyToAndFromItsAlternatives()
         {
-            var operation = new AsyncApiOperation();
-            operation.Bindings.Add(new SolaceOperationBinding
-            {
-                TimeToLive = new SolaceIntegerOrSchema(),
-            });
+            var schema = new AsyncApiJsonSchema { Type = SchemaType.Integer };
+            var binding = new SolaceOperationBinding { TimeToLive = 2592000000L, Priority = schema };
+
+            long timeToLive = binding.TimeToLive.Should().BeOfType<SolaceInteger>().Subject;
+            AsyncApiJsonSchema priority = binding.Priority.Should().BeOfType<SolaceIntegerSchema>().Subject;
 
-            var exception = FluentActions.Invoking(() => operation.SerializeAsYaml(AsyncApiVersion.AsyncApi2_0))
-                .Should().Throw<System.InvalidOperationException>()
-                .Which;
-            exception.Message.Should().Contain("must contain an integer or a schema");
+            timeToLive.Should().Be(2592000000L);
+            priority.Should().BeSameAs(schema);
         }
 
         [TestCase(AsyncApiVersion.AsyncApi2_0)]