field_struct 0.15.0

data/lib/field_struct/types/float.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module FieldStruct
+  module Types
+    # Float type. Coerces via +Kernel#Float+, which parses numeric strings
+    # strictly and rejects anything non-numeric. Strings are base 10, as for
+    # {Types::Integer}: a hex string like "0x1A", which +Kernel#Float+ would
+    # read as 26.0, is refused.
+    class Float < Base
+      # A string +Kernel#Float+ would read as hex: optional whitespace and
+      # sign, then +0x+. (Binary and octal prefixes it already refuses.)
+      # @return [::Regexp]
+      HEX_PREFIX = /\A\s*[+-]?0x/i
+      # Native options: a +round:+ Integer precision and an +in:+ Array or
+      # Range of allowed values.
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {
+          round: option(type: [::Integer]),
+          in: option(type: [::Array, ::Range])
+        }
+      end
+
+      # @return [::Integer, nil] field-level rounding precision; +nil+ disables.
+      def self.default_round
+        nil
+      end
+
+      # @param value [Numeric, ::String, nil] +nil+ → +nil+; everything
+      #   else flows through +Kernel#Float+ — strict on string parsing,
+      #   rejects non-numeric strings, Symbols, Booleans, Arrays, and
+      #   hex strings ("0x1A").
+      # @param round [::Integer, nil] decimal places, rounding half up (ties
+      #   away from zero); +nil+ leaves the value unrounded. The result is a
+      #   Float even at +round: 0+.
+      # @return [::Float, nil] +nil+ for +nil+ input, otherwise the parsed float
+      # @raise [ArgumentError, TypeError] when the value cannot be coerced
+      #   (a String that is not a number, a Complex), or coerces to NaN or
+      #   ±Infinity (including a String like "1e400")
+      def coerce(value, round: self.class.default_round, **)
+        return nil if value.nil?
+
+        result = value.is_a?(::Float) ? value : parse(value)
+        # The class, never the value — see Types::Time#coerce.
+        raise ArgumentError, "Float fields expect a finite number, got a non-finite #{value.class}" unless result.finite?
+
+        # Float#round returns an Integer at round: 0; .to_f keeps the
+        # field's type. half: :up pins ties away from zero.
+        round ? result.round(round, half: :up).to_f : result
+      end
+
+      # @return [Class] the top-level +::Float+ class
+      def ruby_type
+        ::Float
+      end
+
+      private
+
+      # @param value [Object] a non-Float value
+      # @return [::Float]
+      # @raise [ArgumentError] when it is a hex string or +Kernel#Float+
+      #   refuses it; the message names the class, never the value
+      #   (Kernel's own message echoes it)
+      def parse(value)
+        if value.is_a?(::String) && HEX_PREFIX.match?(value)
+          raise ArgumentError, 'Float fields expect a base-10 number, got a String that is not one'
+        end
+
+        begin
+          ::Kernel.Float(value)
+        rescue ::ArgumentError, ::RangeError
+          raise ArgumentError, "Float fields could not read a #{value.class} as a number", cause: nil
+        end
+      end
+    end
+  end
+end

data/lib/field_struct/types/immutable_string.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'string'
+
+module FieldStruct
+  module Types
+    # Like {Types::String}, but the coerced value is frozen. Useful when
+    # downstream code must not mutate a stored string.
+    class ImmutableString < FieldStruct::Types::String
+      # @param value [#to_s, nil] anything stringable; +nil+ stays +nil+
+      # @return [::String, nil] frozen string, or +nil+ if input is +nil+
+      def coerce(value, **)
+        result = super
+        result.nil? ? nil : result.dup.freeze
+      end
+    end
+  end
+end

data/lib/field_struct/types/integer.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module FieldStruct
+  module Types
+    # Integer type. Strings parse in base 10 unless the field declares a
+    # +base:+, so "010" is ten (not octal eight) and "0x1A" is refused rather
+    # than read as hex. Float-shaped strings like "3.14" raise rather than
+    # silently truncate. Float numerics, by contrast, are truncated — that
+    # matches +Kernel#Integer+'s own behavior on numeric input — unless the
+    # field declares +strict: true+, which refuses any non-integral value.
+    class Integer < Base
+      # The radixes +Kernel#Integer+ accepts for a +base:+ option.
+      # @return [::Range<::Integer>]
+      BASES = (2..36)
+
+      # Native options: an +in:+ Array or Range of allowed values, a
+      # +base:+ Integer radix (2..36) for string input, and a +strict:+
+      # Boolean.
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {
+          in: option(type: [::Array, ::Range]),
+          base: option(type: [::Integer]),
+          strict: option(type: [::TrueClass, ::FalseClass])
+        }
+      end
+
+      # Refuse a +base:+ outside 2..36 at field-declaration time. A
+      # non-Integer +base:+ is left for the option-shape check to report.
+      #
+      # @param options [::Hash{::Symbol => Object, nil}] the per-field options hash
+      # @return [::Hash{::Symbol => Object, nil}] the options, unchanged
+      # @raise [ArgumentError] when +base:+ is an Integer outside 2..36
+      def self.resolve_options(options)
+        base = options[:base]
+        if base.is_a?(::Integer) && !BASES.cover?(base)
+          raise ArgumentError, "base: on Integer expects an Integer from 2 to 36, got #{base}"
+        end
+
+        options
+      end
+
+      # @param value [::Integer, Numeric, ::String, nil] +nil+ → +nil+;
+      #   +Integer+ passes through; a String parses in +base+ (surrounding
+      #   whitespace and digit underscores allowed; float-shaped or
+      #   out-of-base strings raise ArgumentError); other numerics flow
+      #   through +Kernel#Integer+ — Floats are truncated;
+      #   Symbols/Booleans/Arrays raise TypeError.
+      # @param base [::Integer, nil] radix (2..36) for String input; +nil+
+      #   means 10
+      # @param strict [Boolean, nil] when true, refuse a value that is not a
+      #   whole number (+12.7+, a +Time+) instead of truncating it; an
+      #   integral one (+12.0+) still becomes its Integer
+      # @return [::Integer, nil] +nil+ for +nil+ input, otherwise the parsed integer
+      # @raise [ArgumentError, TypeError] when the value cannot be coerced,
+      #   including a NaN or ±Infinity Numeric (Float, BigDecimal) and a
+      #   Complex with an imaginary part
+      def coerce(value, base: 10, strict: false, **)
+        return nil if value.nil?
+        return value if value.is_a?(::Integer)
+        return parse_string(value, base || 10) if value.is_a?(::String)
+        if value.is_a?(::Numeric) && !value.finite?
+          # The class, never the value — see Types::Time#coerce.
+          raise ArgumentError, "Integer fields expect a finite number, got a non-finite #{value.class}"
+        end
+
+        refuse_huge_decimal!(value)
+
+        whole = begin
+          ::Kernel.Integer(value)
+        rescue ::RangeError
+          # A Complex with an imaginary part; Kernel's message echoes the value.
+          raise ArgumentError, "Integer fields could not read a #{value.class} as a number", cause: nil
+        end
+        refuse_inexact!(value, whole) if strict
+        whole
+      end
+
+      # The most integer digits a decimal may expand to. +BigDecimal('1e10000000')+
+      # is 11 bytes, but its Integer takes seconds to build, so untrusted JSON
+      # could burn CPU. The same limit as Python's int/str conversion
+      # (CVE-2020-10735).
+      #
+      # @return [::Integer]
+      MAX_DECIMAL_DIGITS = 4300
+
+      # @return [Class] the top-level +::Integer+ class
+      def ruby_type
+        ::Integer
+      end
+
+      private
+
+      # @param value [Object]
+      # @return [void]
+      # @raise [ArgumentError] when +value+ is a decimal whose integer part has
+      #   more than {MAX_DECIMAL_DIGITS} digits
+      def refuse_huge_decimal!(value)
+        return unless defined?(::BigDecimal) && value.is_a?(::BigDecimal)
+        return if value.exponent <= MAX_DECIMAL_DIGITS
+
+        raise ArgumentError, "Integer fields read a decimal of at most #{MAX_DECIMAL_DIGITS} digits, " \
+                             "got a larger #{value.class}"
+      end
+
+      # @param value [Object] the input, already read by +Kernel#Integer+
+      # @param whole [::Integer] what +Kernel#Integer+ made of it
+      # @return [void]
+      # @raise [ArgumentError] unless +whole+ equals +value+ — i.e. the read
+      #   truncated a fraction, or went through +to_i+ on a non-number
+      def refuse_inexact!(value, whole)
+        return if whole == value
+
+        # The class, never the value — see Types::Time#coerce.
+        raise ArgumentError, "Integer fields with strict: true expect a whole number, got a #{value.class} that is not one"
+      end
+
+      # @param value [::String]
+      # @param base [::Integer]
+      # @return [::Integer]
+      # @raise [ArgumentError] when the string is not an integer in +base+
+      def parse_string(value, base)
+        ::Kernel.Integer(value, base)
+      rescue ::ArgumentError
+        # The class, never the value — see Types::Time#coerce.
+        raise ArgumentError, "Integer fields expect a base-#{base} integer, got a String that is not one", cause: nil
+      end
+    end
+  end
+end

data/lib/field_struct/types/nested.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module FieldStruct
+  module Types
+    # Type wrapper for nested FieldStruct fields.
+    #
+    #   class Address < FieldStruct::Base
+    #     required :street, :string
+    #     required :city,   :string
+    #   end
+    #
+    #   class Person < FieldStruct::Base
+    #     required :address, Address
+    #   end
+    #
+    # Built and held per-Field by the DSL when it sees a class argument
+    # that descends from {FieldStruct::Base}. Each instance is
+    # parameterized by its target +struct_class+; instances are not
+    # interchangeable across different nested classes.
+    class Nested < Base
+      # @return [Class] the FieldStruct::Base subclass this type wraps
+      attr_reader :struct_class
+
+      # @param struct_class [Class] a FieldStruct::Base subclass
+      def initialize(struct_class)
+        super()
+        @struct_class = struct_class
+      end
+
+      # Coerce input into a {#struct_class} instance.
+      #
+      # - +nil+ → +nil+
+      # - already a {#struct_class} (or subclass) instance → passthrough
+      # - +Hash+ → +struct_class.new(hash)+
+      # - anything else → +TypeError+ (which the parent's coercion_policy
+      #   handles like any shape-level coercion failure)
+      #
+      # Errors raised inside +struct_class.new+ (e.g.
+      # {UnknownAttributeError}, {CoercionError}) propagate to the caller
+      # rather than being caught by the parent's policy — those are
+      # structural rejections of the nested record's input, not parent-
+      # shape coercion failures.
+      #
+      # @param value [FieldStruct::Base, ::Hash{::Symbol, ::String => Object, nil}, nil] +nil+ → +nil+; an
+      #   instance of {#struct_class} (or subclass) → passthrough; a
+      #   +Hash+ → constructs via +struct_class.new(hash)+. Anything
+      #   else raises TypeError.
+      # @return [FieldStruct::Base, nil]
+      # @raise [TypeError] when input is non-nil and neither a
+      #   {#struct_class} instance nor a Hash
+      def coerce(value, **)
+        return nil if value.nil?
+        return value if value.is_a?(@struct_class)
+        return @struct_class.new(value) if value.is_a?(::Hash)
+
+        raise ::TypeError, "expected #{@struct_class} or Hash, got #{value.class}"
+      end
+
+      # @param value [Object]
+      # @return [Boolean] true only when value is nil — an instance with
+      #   all required fields missing is not "missing" here, it is just
+      #   invalid. Invalidity is surfaced by the parent's validate_field.
+      def missing?(value)
+        value.nil?
+      end
+
+      # @return [Class] the +struct_class+ itself, so introspection sees
+      #   the actual nested type rather than a generic FieldStruct::Base
+      def ruby_type
+        @struct_class
+      end
+
+      # @return [::String]
+      def inspect
+        name = @struct_class.name || 'AnonymousFieldStruct'
+        "#<#{FieldStruct.inspect_namespace}::Types::Nested struct_class=#{name}>"
+      end
+    end
+  end
+end

data/lib/field_struct/types/preset_resolver.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module FieldStruct
+  module Types
+    # Generic preset resolution for a single named option on a single
+    # type. Symbol values are looked up in the supplied presets hash;
+    # anything else passes through. Unknown preset names raise
+    # +ArgumentError+ at field-declaration time.
+    #
+    # Used by string-shaped types (Email/UUID/URL) for +format:+ and by
+    # time-shaped types (Date/Time/DateTime) via {TimeFormatResolver}
+    # (which adds a stricter set of allowed value types).
+    module PresetResolver
+      # Resolve +options[key]+ when it's a Symbol preset name, leaving other
+      # values untouched.
+      #
+      # @param options [::Hash{::Symbol => Object, nil}] the per-field options
+      # @param key [::Symbol] the option to resolve (e.g. +:format+)
+      # @param presets [::Hash{::Symbol => Object}] preset name → concrete value
+      # @param label [::String] used in the unknown-preset error message
+      # @return [::Hash{::Symbol => Object, nil}] options with +key+ resolved (a copy when changed)
+      # @raise [ArgumentError] when +options[key]+ names an unknown preset
+      def self.call(options, key, presets, label:)
+        return options unless options.key?(key)
+
+        value = options[key]
+        return options unless value.is_a?(::Symbol)
+
+        resolved = presets.fetch(value) do
+          raise ArgumentError,
+            "unknown #{label} preset #{value.inspect}. Available: #{presets.keys.inspect}"
+        end
+        options.merge(key => resolved)
+      end
+    end
+  end
+end

data/lib/field_struct/types/rfc3339_format.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'time'
+
+module FieldStruct
+  module Types
+    # RFC 3339 — the profile of ISO 8601 that "ISO-8601" means in an API
+    # contract, and what JSON Schema's +date-time+ refers to. This is what the
+    # +:iso8601+ preset resolves to for {Date}, {Time} and {DateTime}.
+    #
+    # FieldStruct parses and renders it itself, for two reasons.
+    #
+    # **It cannot be written as a strftime string.** +%z+ renders +\+0000+,
+    # which RFC 3339 rejects — so the preset named +iso8601+ used to emit a
+    # value its own documented format would refuse. And no strftime string can
+    # express "optional fractional seconds", which most JSON APIs emit.
+    #
+    # **The stdlib helpers disagree with each other.** Routing +Time+ through
+    # +Time.iso8601+ and +DateTime+ through +DateTime.iso8601+ would give the
+    # same declared preset two different contracts:
+    #
+    #     Time.iso8601('2026-02-30T10:30:00Z')      # => 2026-03-02 10:30 UTC
+    #     DateTime.iso8601('2026-02-30T10:30:00Z')  # => refused
+    #     Time.iso8601('2026-07-03T10:30Z')         # => refused
+    #     DateTime.iso8601('2026-07-03T10:30Z')     # => accepted
+    #     DateTime.iso8601('10:30:00Z')             # => TODAY at 10:30
+    #
+    # +Time.iso8601+ reading 30 February as 2 March is the exact
+    # silently-wrong-day defect this release exists to remove, so it cannot be
+    # the thing that implements the strict preset.
+    #
+    # The pattern is deliberately narrow: fixed-width fields, a mandatory
+    # offset, and no week dates, ordinal dates or basic (unseparated) forms.
+    # That narrowness is the point — it is what lets a caller replace a
+    # hand-rolled +/\A\d{4}-\d{2}-\d{2}\z/+ with a declared format.
+    class Rfc3339Format
+      # Full-width calendar date. No sign, no week or ordinal forms.
+      # @return [::Regexp]
+      DATE = /\A(\d{4})-(\d{2})-(\d{2})\z/
+
+      # Date, +T+, time to whole seconds, optional fraction, mandatory offset.
+      # +±hhmm+ (no colon) is accepted on input because that is what FieldStruct
+      # v0.9.0 emitted, and its own output has to keep parsing.
+      #
+      # @return [::Regexp]
+      TIMESTAMP = /\A(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(\.\d+)?([Zz]|[+-]\d{2}:?\d{2})\z/
+
+      # @return [Rfc3339Format] the date-only form, for {Types::Date}
+      def self.date
+        @date ||= new(:date)
+      end
+
+      # @return [Rfc3339Format] the timestamp form, for {Types::Time} and {Types::DateTime}
+      def self.timestamp
+        @timestamp ||= new(:timestamp)
+      end
+
+      # @return [::Symbol] +:date+ or +:timestamp+
+      attr_reader :kind
+
+      # @param kind [::Symbol] +:date+ or +:timestamp+
+      def initialize(kind)
+        @kind = kind
+        freeze
+      end
+
+      # @return [::Symbol] the preset name this format implements
+      def name
+        :iso8601
+      end
+
+      # The accepted shape, as a regular expression whose source is also valid
+      # as an ECMA pattern — so a schema or documentation generator can publish
+      # the enforced contract rather than a prose approximation of it.
+      #
+      # @return [::Regexp]
+      def pattern
+        kind == :date ? DATE : TIMESTAMP
+      end
+
+      # @return [::String] the format's name, for error messages and inspection
+      def to_s
+        'iso8601 (RFC 3339)'
+      end
+
+      # Parse a String into date/time fragments.
+      #
+      # @param value [::String] the raw string
+      # @return [::Hash{::Symbol => Object}] +:year+, +:mon+, +:mday+ and, for a
+      #   timestamp, +:hour+, +:min+, +:sec+, +:sec_fraction+, +:offset+
+      # @raise [ArgumentError] when the string is not RFC 3339, or names a day,
+      #   hour, minute or second that cannot exist
+      def parse(value)
+        match = pattern.match(value)
+        # The value is not echoed: FieldStruct wraps this as "could not be
+        # coerced: <message>" and that string reaches API responses.
+        raise ArgumentError, "expected an RFC 3339 #{kind}" if match.nil?
+
+        kind == :date ? date_parts(match) : timestamp_parts(match)
+      end
+
+      # Render a coerced value back to RFC 3339.
+      #
+      # @param value [::Date, ::Time, ::DateTime] the coerced value
+      # @return [::String]
+      def render(value)
+        # Date#iso8601, never Date#xmlschema: ActiveSupport redefines the
+        # latter to emit a full timestamp, which would make output depend on
+        # whether the host loaded Rails.
+        return value.iso8601 if kind == :date
+
+        "#{value.strftime("%Y-%m-%dT%H:%M:%S")}#{fraction_of(value)}#{offset_of(value)}"
+      end
+
+      private
+
+      # @param match [::MatchData] a {DATE} match
+      # @return [::Hash{::Symbol => ::Integer}]
+      def date_parts(match)
+        year, month, day = match.captures.map { |capture| Integer(capture, 10) }
+        TemporalParser.ensure_real_day!({year: year, mon: month, mday: day})
+
+        {year: year, mon: month, mday: day}
+      end
+
+      # @param match [::MatchData] a {TIMESTAMP} match
+      # @return [::Hash{::Symbol => Object}]
+      def timestamp_parts(match)
+        year, month, day, hour, minute, second = match.captures[0, 6].map { |c| Integer(c, 10) }
+        TemporalParser.ensure_real_day!({year: year, mon: month, mday: day})
+        # RFC 3339 permits a leap second, but Time rolls :60 into the next
+        # minute and DateTime clamps it to :59 — the two stdlib classes give
+        # different answers, so the strict preset refuses it rather than
+        # picking one silently. Hour 24 is not RFC 3339 at all.
+        raise ArgumentError, 'invalid time of day' if hour > 23 || minute > 59 || second > 59
+
+        {
+          year: year, mon: month, mday: day, hour: hour, min: minute, sec: second,
+          sec_fraction: fraction_from(match.captures[6]),
+          offset: offset_from(match.captures[7])
+        }
+      end
+
+      # @param text [::String, nil] the +.digits+ capture, if any
+      # @return [::Rational] seconds after the whole second, exact
+      def fraction_from(text)
+        return 0r if text.nil?
+
+        ::Kernel.Rational(text[1..], 10**(text.length - 1))
+      end
+
+      # @return [::Integer] seconds east of UTC
+      # @raise [ArgumentError] when the offset names an hour or minute that
+      #   cannot exist. Validated here rather than left to the constructors,
+      #   because they disagree: +Time.new+ refuses a +25:00 offset while
+      #   +DateTime.new+ accepts it and silently drops it to +00:00. A preset
+      #   that means two different things depending on the field's type is the
+      #   defect this class exists to avoid.
+      # @param text [::String] the offset capture: +Z+ or +±hh:mm+ / +±hhmm+
+      def offset_from(text)
+        return 0 if text.casecmp('Z').zero?
+
+        sign = text.start_with?('-') ? -1 : 1
+        digits = text[1..].delete(':')
+        hours = Integer(digits[0, 2], 10)
+        minutes = Integer(digits[2, 2], 10)
+        raise ArgumentError, 'invalid UTC offset' if hours > 23 || minutes > 59
+
+        sign * ((hours * 3600) + (minutes * 60))
+      end
+
+      # @param value [::Time, ::DateTime]
+      # @return [::String] +".123"+, or empty when the value is on a whole second
+      def fraction_of(value)
+        subsec = value.is_a?(::Time) ? value.subsec : value.sec_fraction
+        return '' if subsec.zero?
+
+        # Exact digits from the Rational; %f would round to six places and
+        # invent precision the value never carried.
+        digits = (subsec.to_r * 1_000_000_000).to_i.to_s.rjust(9, '0').sub(/0+\z/, '')
+        ".#{digits}"
+      end
+
+      # @param value [::Time, ::DateTime]
+      # @return [::String] +"Z"+ for UTC, otherwise +"+HH:MM"+
+      def offset_of(value)
+        seconds = value.is_a?(::Time) ? value.utc_offset : (value.offset * 86_400).to_i
+        return 'Z' if seconds.zero?
+
+        sign = seconds.negative? ? '-' : '+'
+        magnitude = seconds.abs
+        format('%s%02d:%02d', sign, magnitude / 3600, (magnitude % 3600) / 60)
+      end
+    end
+  end
+end

data/lib/field_struct/types/string.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module FieldStruct
+  module Types
+    # String type. Coerces any non-nil value via +to_s+; treats nil, empty,
+    # and whitespace-only strings as missing. A field declared +strict: true+
+    # accepts only scalars (String, Symbol, Integer) and objects
+    # responding to +to_str+, so a Hash or Array is refused rather than stored
+    # as its +inspect+ text.
+    class String < Base
+      # Native options: a +format:+ Regexp (or Symbol preset, used by the
+      # +:uuid+ / +:url+ / +:email+ subtypes), an +enum:+ Array of
+      # allowed values, and a +strict:+ Boolean.
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {
+          format: option(type: [::Regexp, ::Symbol]),
+          enum: option(type: [::Array]),
+          strict: option(type: [::TrueClass, ::FalseClass])
+        }
+      end
+
+      # @param value [#to_s, nil] anything stringable (everything in
+      #   Ruby responds to +to_s+); +nil+ stays +nil+
+      # @param strict [Boolean, nil] when true, refuse anything but a String,
+      #   Symbol, Integer or +to_str+ object (a Float, BigDecimal or Rational
+      #   is refused: its +to_s+ is +"0.12e2"+ / +"1/2"+, not the caller's text). Strict never changes
+      #   what an accepted value becomes — it is still +value.to_s+.
+      # @return [::String, nil] +nil+ when input is +nil+, otherwise +value.to_s+
+      # @raise [TypeError] under +strict:+, for any other value
+      def coerce(value, strict: false, **)
+        return nil if value.nil?
+
+        refuse_non_scalar!(value) if strict
+        value.to_s
+      end
+
+      # Missing if nil, empty, or whitespace-only.
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      def missing?(value)
+        return true if value.nil?
+        return true if value.respond_to?(:strip) && value.strip.empty?
+
+        false
+      end
+
+      # @return [Class] the top-level +::String+ class
+      def ruby_type
+        ::String
+      end
+
+      private
+
+      # @param value [Object] a non-nil value
+      # @return [void]
+      # @raise [TypeError] unless +value+ is a String, Symbol, Integer, or
+      #   responds to +to_str+; the message names the class, never the value
+      #   (see Types::Time#coerce)
+      def refuse_non_scalar!(value)
+        return if value.is_a?(::String) || value.is_a?(::Symbol) || value.is_a?(::Integer)
+        return if value.respond_to?(:to_str)
+
+        raise ::TypeError, 'String fields with strict: true expect a String, Symbol, Integer ' \
+                           "or an object responding to #to_str, got a #{value.class}"
+      end
+    end
+  end
+end

data/lib/field_struct/types/symbol.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module FieldStruct
+  module Types
+    # Symbol type. Accepts an existing +Symbol+ or a +String+. Anything else
+    # raises +TypeError+, which the parent's +coercion_policy+ handles.
+    #
+    # Empty symbols (+:""+) are unusual; like other scalar non-string types,
+    # +missing?+ is nil-only — an empty symbol counts as present.
+    class Symbol < Base
+      # Native options: an +enum:+ Array of allowed values (symbols are
+      # string-like, so they share +enum:+ with {Types::String}).
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {enum: option(type: [::Array])}
+      end
+
+      # @param value [::Symbol, ::String, nil] anything else raises TypeError
+      # @return [::Symbol, nil]
+      # @raise [TypeError] when input is not nil/Symbol/String
+      def coerce(value, **)
+        return nil if value.nil?
+        return value if value.is_a?(::Symbol)
+        return value.to_sym if value.is_a?(::String)
+
+        raise ::TypeError, "expected Symbol or String, got #{value.class}"
+      end
+
+      # @return [Class] the top-level +::Symbol+ class
+      def ruby_type
+        ::Symbol
+      end
+    end
+  end
+end