refactor!: model Solace values and StringOrStringList as type hierarchies (#55)

* 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>

* refactor!: model StringOrStringList as a type hierarchy

StringOrStringList is now an abstract base with SingleString and
StringList subtypes instead of wrapping an AsyncApiAny that callers had
to inspect. Implicit conversions from string, string[] and List<string>
replace new StringOrStringList(new AsyncApiAny(...)), and invalid values
(non-strings, null items) can no longer be constructed. The Value
property is replaced by Write(IAsyncApiWriter) for serialization.

BREAKING CHANGE: the public constructor and the Value property are
removed. Construct values through the implicit conversions or the
SingleString/StringList constructors.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: bielu

src/ByteBard.AsyncAPI.Bindings/Sns/Condition.cs

@@ -27,7 +27,7 @@ public void Serialize(IAsyncApiWriter writer)
         writer.WriteStartObject();
         foreach (var conditionValue in this.Value)
         {
-            writer.WriteRequiredMap(conditionValue.Key, conditionValue.Value, (w, t) => t.Value.Write(w));
+            writer.WriteRequiredMap(conditionValue.Key, conditionValue.Value, (w, t) => t.Write(w));
         }
 
         writer.WriteEndObject();

src/ByteBard.AsyncAPI.Bindings/Sns/PrincipalObject.cs

@@ -21,7 +21,7 @@ public override void Serialize(IAsyncApiWriter writer)
         }
 
         writer.WriteStartObject();
-        writer.WriteRequiredObject(this.Value.Key, this.Value.Value, (w, t) => t.Value.Write(w));
+        writer.WriteRequiredObject(this.Value.Key, this.Value.Value, (w, t) => t.Write(w));
         writer.WriteEndObject();
     }
 }

src/ByteBard.AsyncAPI.Bindings/Sns/Statement.cs

@@ -45,8 +45,8 @@ public void Serialize(IAsyncApiWriter writer)
             writer.WriteStartObject();
             writer.WriteRequiredProperty("effect", this.Effect.GetDisplayName());
             writer.WriteRequiredObject("principal", this.Principal, (w, t) => t.Serialize(w));
-            writer.WriteRequiredObject("action", this.Action, (w, t) => t.Value.Write(w));
-            writer.WriteOptionalObject("resource", this.Resource, (w, t) => t?.Value.Write(w));
+            writer.WriteRequiredObject("action", this.Action, (w, t) => t.Write(w));
+            writer.WriteOptionalObject("resource", this.Resource, (w, t) => t?.Write(w));
             writer.WriteOptionalObject("condition", this.Condition, (w, t) => t.Serialize(w));
             writer.WriteExtensions(this.Extensions);
             writer.WriteEndObject();

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); });

src/ByteBard.AsyncAPI.Bindings/Sqs/Condition.cs

@@ -27,7 +27,7 @@ public void Serialize(IAsyncApiWriter writer)
         writer.WriteStartObject();
         foreach (var conditionValue in this.Value)
         {
-            writer.WriteRequiredMap(conditionValue.Key, conditionValue.Value, (w, t) => t.Value.Write(w));
+            writer.WriteRequiredMap(conditionValue.Key, conditionValue.Value, (w, t) => t.Write(w));
         }
 
         writer.WriteEndObject();

src/ByteBard.AsyncAPI.Bindings/Sqs/PrincipalObject.cs

@@ -21,7 +21,7 @@ public override void Serialize(IAsyncApiWriter writer)
         }
 
         writer.WriteStartObject();
-        writer.WriteRequiredObject(this.Value.Key, this.Value.Value, (w, t) => t.Value.Write(w));
+        writer.WriteRequiredObject(this.Value.Key, this.Value.Value, (w, t) => t.Write(w));
         writer.WriteEndObject();
     }
 }

src/ByteBard.AsyncAPI.Bindings/Sqs/Statement.cs

@@ -45,8 +45,8 @@ public void Serialize(IAsyncApiWriter writer)
             writer.WriteStartObject();
             writer.WriteRequiredProperty("effect", this.Effect.GetDisplayName());
             writer.WriteRequiredObject("principal", this.Principal, (w, t) => t.Serialize(w));
-            writer.WriteRequiredObject("action", this.Action, (w, t) => t.Value.Write(w));
-            writer.WriteOptionalObject("resource", this.Resource, (w, t) => t?.Value.Write(w));
+            writer.WriteRequiredObject("action", this.Action, (w, t) => t.Write(w));
+            writer.WriteOptionalObject("resource", this.Resource, (w, t) => t?.Write(w));
             writer.WriteOptionalObject("condition", this.Condition, (w, t) => t.Serialize(w));
             writer.WriteExtensions(this.Extensions);
             writer.WriteEndObject();