field_struct 0.15.0

data/lib/field_struct/types/temporal_parser.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module FieldStruct
+  module Types
+    # Shared String-parsing rules for {Date}, {Time} and {DateTime}.
+    #
+    # Three rules the stdlib parsers leave to their caller. Each of them is a
+    # case where the stdlib answers a question it was not asked, confidently.
+    #
+    # **Anchoring.** +strptime+ matches a PREFIX and discards the rest.
+    # +Date.strptime('2026-07-031', '%Y-%m-%d')+ returns the 3rd and throws the
+    # trailing +1+ away; +'2026-07-03T10:30:00+0000-NONSENSE'+ parses clean
+    # under the +iso8601+ preset. A declared +format:+ is a contract about the
+    # whole string, so anything left over is refused. (Leading whitespace needs
+    # no rule — +Date._strptime+ already returns +nil+ for it.)
+    #
+    # **Civil validity.** +Date.strptime+ and +DateTime.strptime+ refuse the
+    # 30th of February. +Time+ does not: +Time.parse+, +Time.strptime+ and
+    # +Time.new+ all roll it forward to 2 March and say nothing. All three
+    # types refuse it here.
+    #
+    # **Completeness.** With no declared format the stdlib parsers fill in
+    # whatever the string omits, from *today*: +Time.parse('10:30')+ is today
+    # at 10:30, +'July'+ is the 1st of July this year, +'12'+ is the 12th of
+    # this month. A value whose meaning depends on when it was parsed is not a
+    # value, so a string with no declared format must name a whole day.
+    #
+    # Anchoring is trailing-junk rejection and nothing more. Widths, sign and
+    # case stay strptime-lenient for a hand-written format: +%m+ and +%d+
+    # accept one or two digits, which is strptime's contract rather than a
+    # defect. Strictness for the built-in presets is a separate concern.
+    module TemporalParser
+      # Validate a String against a declared format.
+      #
+      # @param value [::String] the raw string
+      # @param format [::String] a resolved strftime/strptime format
+      # @return [::Hash{::Symbol => Object}] the parsed fragments
+      # @raise [ArgumentError] when the string does not match the format, has
+      #   characters left over, or names a day that does not exist
+      def self.strptime_parts(value, format)
+        parts = ::Date._strptime(value, format)
+        raise ArgumentError, "does not match format #{format.inspect}" if parts.nil?
+
+        if parts.key?(:leftover)
+          raise ArgumentError,
+            "does not match format #{format.inspect} — unexpected trailing characters"
+        end
+
+        ensure_real_day!(parts)
+        parts
+      end
+
+      # Validate a String with no declared format.
+      #
+      # @param value [::String] the raw string
+      # @return [::Hash{::Symbol => Object}] the parsed fragments
+      # @raise [ArgumentError] when the string names only part of a day, or a
+      #   day that does not exist
+      def self.parse_parts(value)
+        parts = ::Date._parse(value)
+        ensure_whole_day!(parts)
+        ensure_real_day!(parts)
+        parts
+      end
+
+      # @param parts [::Hash{::Symbol => Object}] fragments from +Date._parse+
+      # @return [void]
+      # @raise [ArgumentError] when year, month or day is missing
+      def self.ensure_whole_day!(parts)
+        return if parts[:year] && parts[:mon] && parts[:mday]
+
+        # The value is deliberately not echoed: FieldStruct wraps this as
+        # "could not be coerced: <message>" and that string reaches API
+        # responses and audit rows.
+        raise ArgumentError, 'expected a date with a year, a month and a day'
+      end
+
+      # @param parts [::Hash{::Symbol => Object}] fragments from +Date._parse+
+      #   or +Date._strptime+
+      # @return [void]
+      # @raise [ArgumentError] when the fragments name a day that never existed
+      def self.ensure_real_day!(parts)
+        year, month, day = parts.values_at(:year, :mon, :mday)
+        return if year.nil? || month.nil? || day.nil?
+        return if ::Date.valid_civil?(year, month, day)
+
+        raise ArgumentError, 'invalid date'
+      end
+    end
+  end
+end

data/lib/field_struct/types/time.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'time'
+require_relative 'base'
+
+module FieldStruct
+  module Types
+    # Time type. Returns a +Time+ as-is, builds one from a +Date+ or
+    # +DateTime+'s components, reads a String via +Time.parse+ (or +strptime+
+    # when the field declares a +format:+), and refuses everything else.
+    #
+    # Per-field +format:+ option (String or Symbol-preset) controls both
+    # parsing (strptime when input is a String) and serialization
+    # (strftime via +as_json+).
+    class Time < Base
+      # Native options: a +format:+ strftime/strptime String (or Symbol
+      # preset; see {.presets}), an +in:+ Array or Range of allowed values,
+      # and a +zone:+ String (+"UTC"+, +"±HH:MM"+ or an IANA name; see {ZoneOption}).
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {
+          format: option(type: [::String, ::Symbol], presets: presets.keys),
+          in: option(type: [::Array, ::Range]),
+          zone: option(type: [::String])
+        }
+      end
+
+      # @return [::String, nil]
+      def self.default_format
+        nil
+      end
+
+      # Named presets for the +format:+ option.
+      #
+      # +:iso8601+ is an {Rfc3339Format} rather than a strftime String: +%z+
+      # renders +\+0000+, which RFC 3339 rejects, and no strftime string can
+      # express optional fractional seconds. The interchange and display
+      # presets stay strftime-based.
+      #
+      # @return [Hash{::Symbol=>Object}]
+      def self.presets
+        {
+          iso8601: Rfc3339Format.timestamp,
+          rfc2822: '%a, %d %b %Y %H:%M:%S %z',
+          db: '%Y-%m-%d %H:%M:%S'
+        }
+      end
+
+      # Validate a Symbol +format:+ preset (see {.presets}) and a +zone:+
+      # (see {ZoneOption}) at field-declaration time.
+      #
+      # @param options [::Hash{::Symbol => Object, nil}] the per-field options
+      # @return [::Hash{::Symbol => Object, nil}] the options, unchanged
+      # @raise [ArgumentError] on an unknown preset or an unreadable +zone:+
+      def self.resolve_options(options)
+        ZoneOption.validate!('Time', TimeFormatResolver.call(options, presets))
+      end
+
+      # Resolve a declared +format:+ (a Symbol preset name or a strftime
+      # String) into the String that {#coerce} and JSON rendering actually
+      # use. Declarations are stored exactly as written, so this is where a
+      # preset name becomes usable. See {TimeFormatResolver}.
+      #
+      # @param format [::String, ::Symbol, nil] the format as declared
+      # @return [::String, nil] +nil+ when the field declares no format
+      # @raise [ArgumentError] when a Symbol names no preset in {.presets}
+      def self.resolve_format(format)
+        # Skip building the presets Hash for the common, undeclared case.
+        return format if format.nil? || format.is_a?(::String)
+
+        TimeFormatResolver.resolve(format, presets)
+      end
+
+      # Dispatch is on explicit stdlib classes, never on a +respond_to?+ probe
+      # against the value. ActiveSupport defines +String#to_time+, and it
+      # returns +nil+ for a string with no time in it rather than raising — so
+      # under Rails "not-a-time" was coerced to nil and reported VALID. The
+      # probe is gone; +Time.parse+ and +Time.strptime+ behave the same with or
+      # without ActiveSupport loaded.
+      #
+      # Cross-class conversion builds a Time from components rather than
+      # calling +to_time+, which ActiveSupport redefines: under AS 7.2
+      # +DateTime#to_time+ converts to the system-local zone and emits a
+      # deprecation warning, while 8.x preserves the offset. Constructing from
+      # parts gives the same instant and the same offset in all three
+      # environments, which is what makes the behaviour host-independent rather
+      # than merely documented.
+      #
+      # @param value [::String, ::Time, ::Date, ::DateTime, nil] +nil+ → +nil+;
+      #   a String is read through +strptime+ when a +format:+ is set and
+      #   +Time.parse+ otherwise; a +Time+ passes through; a +DateTime+, +Date+
+      #   or Time-like value (ActiveSupport's TimeWithZone) is converted.
+      #   Anything else is refused.
+      # @param format [::String, nil] strptime/strftime format; +nil+ uses
+      #   {.default_format} (which itself defaults to +nil+ = ISO-8601 path)
+      # @param zone [::String, nil] +"UTC"+, +"±HH:MM"+ or an IANA name: the offset for a
+      #   String that names none, and for a +Date+'s midnight. Input carrying
+      #   its own offset keeps it. +nil+ means the process zone. See {ZoneOption}.
+      # @return [::Time, nil]
+      # @raise [ArgumentError] when a String cannot be parsed, or the value is
+      #   not a String or a temporal object
+      def coerce(value, format: self.class.default_format, zone: nil, **)
+        return nil if value.nil?
+
+        fmt = self.class.resolve_format(format)
+
+        case value
+        when ::String then parse_string(value, fmt, zone)
+        # ::DateTime before ::Date — DateTime is a subclass of Date, and only
+        # this arm carries the time of day.
+        when ::DateTime then time_from_datetime(value)
+        when ::Date then zone ? ZoneOption.midnight(value, zone) : ::Time.new(value.year, value.mon, value.mday)
+        # A TimeWithZone matches here (AS overrides Time.===) but is NOT an
+        # instance of ::Time, so it must be converted rather than passed
+        # through — otherwise a :time field would store a TWZ.
+        when ::Time then value.instance_of?(::Time) ? value : ::Time.at(value.to_r).getlocal(value.utc_offset)
+        else
+          # The class, never the value — see Types::Date#coerce.
+          raise ArgumentError, "expected a String, Date, DateTime or Time, got #{value.class}"
+        end
+      end
+
+      # @return [Class] the top-level +::Time+ class
+      def ruby_type
+        ::Time
+      end
+
+      private
+
+      # @param value [::String] the raw string
+      # @param format [::String, nil] strptime format, when the field declares one
+      # @param zone [::String, nil] the field's +zone:+, if declared
+      # @return [::Time]
+      # @raise [ArgumentError] when the string cannot be read
+      def parse_string(value, format, zone)
+        # Validated first, then handed to the stdlib parser: the checks decide
+        # what is ACCEPTABLE, the stdlib still decides what the value IS, so
+        # the two can't drift apart. See {TemporalParser} for the three rules.
+        if format.is_a?(Rfc3339Format)
+          parts = format.parse(value)
+          return ::Time.new(parts[:year], parts[:mon], parts[:mday], parts[:hour], parts[:min],
+            parts[:sec] + parts[:sec_fraction], parts[:offset])
+        end
+
+        if format
+          parts = TemporalParser.strptime_parts(value, format)
+          return ZoneOption.time_at(value, format, zone, parts) if zone && ZoneOption.zoneless?(parts)
+
+          return ::Time.strptime(value, format)
+        end
+
+        parts = TemporalParser.parse_parts(value)
+        return ZoneOption.time_at(value, nil, zone, parts) if zone && ZoneOption.zoneless?(parts)
+
+        ::Time.parse(value)
+      end
+
+      # @param value [::DateTime] the value to convert
+      # @return [::Time] the same instant, at the same offset, sub-second
+      #   precision preserved
+      def time_from_datetime(value)
+        ::Time.new(value.year, value.mon, value.mday, value.hour, value.min,
+          value.sec + value.sec_fraction, value.zone)
+      end
+    end
+  end
+end

data/lib/field_struct/types/time_format_resolver.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module FieldStruct
+  module Types
+    # Shared +format:+ option resolution for {Date}/{Time}/{DateTime}.
+    # Each of those types calls +TimeFormatResolver.call(options, presets)+
+    # from its +resolve_options+ class method.
+    #
+    # A declared +format:+ is VALIDATED at declaration time and kept exactly as
+    # the user wrote it; it is resolved to a strftime string later, at coerce
+    # and render time, by {.resolve}.
+    #
+    # Keeping the declaration is the point. The Symbol used to be overwritten
+    # with the strftime String it expands to, which destroyed the only fact a
+    # documentation generator actually wants — that the field is +:iso8601+,
+    # not some anonymous String of percent-escapes. Recovering the name by
+    # reverse-mapping the String worked only while no two presets shared a
+    # value, which is luck rather than a contract.
+    module TimeFormatResolver
+      # Validate a declared +format:+ and return the options unchanged.
+      #
+      # @param options [::Hash{::Symbol => Object, nil}] the per-field options as written
+      # @param presets [::Hash{::Symbol => ::String}] the type's preset table
+      # @return [::Hash{::Symbol => Object, nil}] +options+, unmodified
+      # @raise [ArgumentError] when +format:+ is the wrong shape, or names a
+      #   preset the type does not have — at declaration time, not at first use
+      def self.call(options, presets)
+        return options unless options.key?(:format)
+
+        fmt = options[:format]
+        return options if fmt.is_a?(::String) || fmt.is_a?(::Regexp) || fmt.nil?
+        raise ArgumentError, "format: must be a String, Regexp, or Symbol — got #{fmt.class}" unless fmt.is_a?(::Symbol)
+
+        resolve(fmt, presets) # raises on an unknown name; the result is discarded
+        options
+      end
+
+      # Resolve a declared +format:+ to a strftime/strptime String.
+      #
+      # @param format [::String, ::Symbol, nil] as declared
+      # @param presets [::Hash{::Symbol => ::String}] the type's preset table
+      # @return [::String, nil] +nil+ when no format is declared
+      # @raise [ArgumentError] when the Symbol names no preset in the table
+      def self.resolve(format, presets)
+        return format if format.nil? || format.is_a?(::String)
+
+        presets.fetch(format) do
+          raise ArgumentError,
+            "unknown time format preset #{format.inspect}. Available: #{presets.keys.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/field_struct/types/union.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module FieldStruct
+  module Types
+    # Union type — a value that may be any of several types. Each
+    # member is tried in declared order; the first one whose +coerce+
+    # doesn't raise wins. Member-coercion errors are caught broadly
+    # (ArgumentError, TypeError, FieldStruct::Error) so a member's
+    # rejection lets the next member have a try; unrelated bugs (e.g.
+    # +NoMethodError+) still propagate.
+    #
+    #   optional :payload, :union, of: [Payload, :boolean]
+    #
+    # If every member rejects the value, the union raises a +TypeError+
+    # which the parent's +coercion_policy+ handles like any
+    # shape-level coercion failure.
+    #
+    # Order matters: +of: [String, Integer]+ coerces "42" to "42"
+    # (String wins first); +of: [Integer, String]+ coerces "42" to 42.
+    class Union < Base
+      # Member-coercion errors caught so the next member can be tried; other
+      # exceptions (e.g. +NoMethodError+) propagate as real bugs.
+      #
+      # @return [::Array<Class<::StandardError>>]
+      RESCUABLE = [ArgumentError, TypeError, FieldStruct::Error].freeze
+
+      # Native options: a required +of:+ Array of member types (the DSL
+      # additionally requires at least two members).
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {of: option(type: [::Array], required: true)}
+      end
+
+      # @return [Array<Types::Base>] the configured member type instances
+      attr_reader :member_types
+
+      # @param member_types [Array<Types::Base>] member instances, in priority order
+      def initialize(member_types)
+        super()
+        @member_types = member_types
+      end
+
+      # @param value [Object, nil] anything — each member type's coerce
+      #   is tried in declared order; the first that doesn't raise wins
+      # @return [Object, nil] whatever the first successful member returns
+      # @raise [TypeError] when no member can coerce, or the value is a
+      #   non-finite number (NaN or ±Infinity), which no member may accept
+      def coerce(value, **)
+        return nil if value.nil?
+        # Refused before any member sees it: a numeric member rejects a
+        # non-finite value with an ArgumentError, which is RESCUABLE, so a
+        # later :string member would otherwise store "NaN" as valid.
+        if value.is_a?(::Numeric) && !value.finite?
+          # The class, never the value — see Types::Time#coerce.
+          raise ::TypeError, "Union fields expect a finite number, got a non-finite #{value.class}"
+        end
+
+        @member_types.each do |type|
+          return type.coerce(value)
+        rescue *RESCUABLE
+          next
+        end
+
+        # The class, never the value — it may be payments data.
+        members = @member_types.map { |m| m.class.name.to_s.split('::').last }.join(' | ')
+        raise ::TypeError, "no union member (#{members}) could coerce #{value.class} input"
+      end
+
+      # @param value [Object]
+      # @return [Boolean] true only for nil — union doesn't try to
+      #   collectively reason about "missing" across its members
+      def missing?(value)
+        value.nil?
+      end
+
+      # Flat list of member +ruby_type+ values. Members whose
+      # ruby_type is already an Array (like Boolean's
+      # +[TrueClass, FalseClass]+) get spliced in; duplicates are
+      # removed.
+      #
+      # @return [Array<Class>]
+      def ruby_type
+        @member_types.flat_map { |type| Array(type.ruby_type) }.uniq
+      end
+
+      # @return [::String]
+      def inspect
+        members = @member_types.map { |m| m.class.name.to_s.split('::').last }.join(' | ')
+        "#<#{FieldStruct.inspect_namespace}::Types::Union of=#{members}>"
+      end
+    end
+  end
+end

data/lib/field_struct/types/url.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'string'
+
+module FieldStruct
+  module Types
+    # URL type — a {Types::String} that pre-fills the field's +format:+
+    # option with a practical http(s) URL pattern. Same shape as
+    # {Types::UUID}: bad-format input is a Phase 1 validation error,
+    # not a coercion failure.
+    #
+    # The default pattern matches +http://+ and +https://+ URLs with a
+    # non-empty host. It is intentionally pragmatic, not RFC 3986
+    # exhaustive — users can override via +format: /.../+ if they need
+    # different schemes or stricter host rules.
+    class URL < FieldStruct::Types::String
+      # Inherits +format:+ / +enum:+ from {Types::String}, advertising the
+      # +:format+ presets this subtype resolves (see {.presets}).
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {format: option(type: [::Regexp, ::Symbol], presets: presets.keys)}
+      end
+
+      # @return [Regexp] practical http(s) pattern; override per-field via +format:+
+      def self.default_format
+        %r{\Ahttps?://[^\s/$.?#][^\s]*\z}i
+      end
+
+      # @return [Hash{::Symbol=>Regexp}] named presets for +format:+
+      def self.presets
+        {
+          http: default_format,
+          https_only: %r{\Ahttps://[^\s/$.?#][^\s]*\z}i,
+          any_scheme: %r{\A[a-z][a-z0-9+\-.]*://[^\s/$.?#][^\s]*\z}i
+        }
+      end
+
+      # Resolve a Symbol +format:+ preset (see {.presets}) to its Regexp at
+      # field-declaration time; a user-supplied Regexp passes through.
+      def self.resolve_options(options)
+        PresetResolver.call(options, :format, presets, label: ':url format')
+      end
+    end
+  end
+end

data/lib/field_struct/types/uuid.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'string'
+
+module FieldStruct
+  module Types
+    # UUID type — a {Types::String} that pre-fills the field's +format:+
+    # option with a canonical RFC-4122 pattern. Bad-format input becomes
+    # a Phase 1-style validation error (+"is invalid"+); coercion itself
+    # still just hands back the string.
+    #
+    # Users can override the pattern by passing +format: /.../+ on the
+    # field declaration.
+    class UUID < FieldStruct::Types::String
+      # Inherits +format:+ / +enum:+ from {Types::String}, advertising the
+      # +:format+ presets this subtype resolves (see {.presets}).
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {format: option(type: [::Regexp, ::Symbol], presets: presets.keys)}
+      end
+
+      # Hex-digit-only canonical RFC-4122 form. Permits any version.
+      #
+      # @return [Regexp] applied at the field level when no +format:+ is given
+      def self.default_format
+        /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/i
+      end
+
+      # @return [Hash{::Symbol=>Regexp}] named presets for +format:+
+      def self.presets
+        {
+          any_version: default_format,
+          v4: /\A\h{8}-\h{4}-4\h{3}-[89ab]\h{3}-\h{12}\z/i,
+          v7: /\A\h{8}-\h{4}-7\h{3}-[89ab]\h{3}-\h{12}\z/i
+        }
+      end
+
+      # Resolve a Symbol +format:+ preset (see {.presets}) to its Regexp at
+      # field-declaration time; a user-supplied Regexp passes through.
+      def self.resolve_options(options)
+        PresetResolver.call(options, :format, presets, label: ':uuid format')
+      end
+    end
+  end
+end

data/lib/field_struct/types/value.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module FieldStruct
+  module Types
+    # Value type. A no-coercion passthrough — whatever you give it comes
+    # back unchanged. Useful as an escape hatch when you want a field
+    # declaration to participate in metadata without committing to a
+    # specific shape.
+    class Value < Base
+      # @param value [Object] anything — passthrough, no coercion
+      # @return [Object] the value, unchanged
+      def coerce(value, **)
+        value
+      end
+
+      # @return [Class] +Object+ — the broadest sensible class
+      def ruby_type
+        ::Object
+      end
+    end
+  end
+end