field_struct 0.15.0

data/lib/field_struct/error.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module FieldStruct
+  # Base class for every error FieldStruct raises. Catch this to handle
+  # any library error generically.
+  class Error < StandardError; end
+
+  # Raised by the setter pipeline when a value cannot be coerced into a
+  # field's declared type and the class's +coercion_policy+ is +:raise+.
+  #
+  # Carries the field name and the original underlying error for callers
+  # that want to inspect what happened.
+  class CoercionError < Error
+    # @return [Symbol, nil] the field whose setter triggered the failure
+    attr_reader :field_name
+
+    # @return [StandardError, nil] the underlying error from the type's coerce
+    attr_reader :original
+
+    # @param message [String]
+    # @param field_name [Symbol, nil]
+    # @param original [StandardError, nil]
+    def initialize(message, field_name: nil, original: nil)
+      super(message)
+      @field_name = field_name
+      @original = original
+    end
+  end
+
+  # Raised when a field setter on a class marked +immutable!+ is called
+  # after construction.
+  class ImmutableError < Error; end
+
+  # Raised by {Base#initialize} / {Base#assign_attributes} when the input
+  # hash includes a key that is not a declared field on the class and
+  # the +unknown_attributes+ policy is +:raise+.
+  class UnknownAttributeError < Error
+    # @return [Array<Symbol>] the offending keys
+    attr_reader :keys
+
+    # @param message [String]
+    # @param keys [Array<Symbol>]
+    def initialize(message, keys: [])
+      super(message)
+      @keys = keys
+    end
+  end
+end

data/lib/field_struct/errors.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module FieldStruct
+  # Per-instance collection of validation messages, keyed by field name.
+  #
+  # Shaped after ActiveModel::Errors but reuses none of its code. Each
+  # FieldStruct instance gets its own Errors object; the setter pipeline
+  # clears and rewrites a field's entry on every assignment.
+  class Errors
+    def initialize
+      @messages = {}
+    end
+
+    # Ruby hook behind +dup+ / +clone+: copy the message lists too, so
+    # adding to the copy never changes the original.
+    #
+    # @api private
+    # @param source [self] the collection being copied
+    # @return [void]
+    def initialize_copy(source)
+      super
+      @messages = source.to_h.transform_values(&:dup)
+    end
+
+    # @param field_name [Symbol, String]
+    # @return [Array<String>] messages for the field, or an empty array
+    def [](field_name)
+      @messages[field_name.to_sym] || []
+    end
+
+    # @param field_name [Symbol, String]
+    # @param message [String]
+    # @return [Array<String>] the field's updated message list
+    def add(field_name, message)
+      key = field_name.to_sym
+      (@messages[key] ||= []) << message
+    end
+
+    # Drop every message for a field.
+    #
+    # @param field_name [Symbol, String]
+    # @return [void]
+    def clear(field_name)
+      @messages.delete(field_name.to_sym)
+      nil
+    end
+
+    # @return [Boolean] true when no field has any messages
+    def empty?
+      # A block loop, not each_value.all?: that builds an Enumerator per call,
+      # and every validity check asks this.
+      @messages.each_value { |messages| return false unless messages.empty? }
+      true
+    end
+
+    # @return [Hash{Symbol=>Array<String>}] snapshot of field → messages,
+    #   skipping fields with empty message lists
+    def to_h
+      @messages.reject { |_, msgs| msgs.empty? }
+    end
+    alias messages to_h
+
+    # Every message rendered as a full, human-readable sentence: the
+    # humanized field name prepended to each message. Messages on +:base+
+    # (the cross-field convention) pass through unprefixed — they are
+    # already complete sentences. Order follows field insertion order, then
+    # message order within a field.
+    #
+    #   errors.add(:first_name, 'is required')
+    #   errors.full_messages   # => ["First name is required"]
+    #
+    # @return [Array<String>]
+    def full_messages
+      to_h.flat_map do |field, msgs|
+        next msgs if field == :base
+
+        prefix = humanize(field)
+        msgs.map { |msg| "#{prefix} #{msg}" }
+      end
+    end
+
+    # @return [String]
+    def inspect
+      prefix = "#{FieldStruct.inspect_namespace}::Errors"
+      return "#<#{prefix} empty>" if empty?
+
+      pairs = to_h.map { |field, msgs| "#{field}=#{msgs.inspect}" }.join(' ')
+      "#<#{prefix} #{pairs}>"
+    end
+
+    private
+
+    # Turn a field name into a display label for {#full_messages}:
+    # underscores become spaces and the first character is upcased.
+    # Deliberately minimal — no inflection, no +_id+ stripping, no i18n.
+    #
+    # @param field [Symbol]
+    # @return [String]
+    def humanize(field)
+      field.to_s.tr('_', ' ').sub(/\A./, &:upcase)
+    end
+  end
+end

data/lib/field_struct/field.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module FieldStruct
+  # A single declared attribute on a FieldStruct class.
+  #
+  # Holds the field's name, the resolved type class, whether it's
+  # required, an optional default, and any remaining keyword options
+  # (e.g. +format:+). Frozen after construction — the DSL is expected
+  # to build a fresh Field rather than mutate one.
+  class Field
+    # @return [Symbol] canonical field name
+    attr_reader :name
+
+    # @return [Class<Types::Base>] the resolved type class
+    attr_reader :type
+
+    # @return [Object, #call, nil] the configured default value, or a
+    #   parameterless callable returning one, or +nil+ if no default
+    attr_reader :default
+
+    # @return [Hash{Symbol=>Object, nil}] frozen, holds the remaining keyword
+    #   options forwarded to {Types::Base#coerce} (e.g. +:format+,
+    #   +:round+, +:values+, +:of_type+, +:enum+, +:in+)
+    attr_reader :options
+
+    # @return [Types::Base] an eagerly-built instance of {#type}, reused by
+    #   the setter pipeline so we don't allocate a fresh type per coercion
+    attr_reader :type_instance
+
+    # @return [:keep_raw, :replace, :raise, nil] this field's coercion-
+    #   failure policy override, or +nil+ to defer to the class-level
+    #   setting on {Base.coercion_policy}.
+    attr_reader :coercion_policy
+
+    # @return [String, nil] human-readable description of the field;
+    #   intended for downstream documentation generators. Not part of
+    #   the data surface — does not appear in +attributes+ / +as_json+ /
+    #   pattern matches.
+    attr_reader :description
+
+    # @return [String, nil] an RBS type expression that {RBS.generate} and
+    #   {RBS.type_for} emit for this field instead of deriving one from the
+    #   type (e.g. +"::ActiveRecord::Relation"+ on a +:value+ field), or
+    #   +nil+ to derive it. Declared with the +rbs_type:+ field option;
+    #   signatures only — it never affects coercion or validation.
+    attr_reader :rbs_type
+
+    # @api private
+    # @return [Symbol] the setter's method name (+:name=+), built once here
+    #   so the setter pipeline doesn't intern a dynamic Symbol per call
+    attr_reader :setter_name
+
+    # @api private
+    # @return [Symbol] the instance variable holding the value (+:@name+),
+    #   built once for the same reason as {#setter_name}
+    attr_reader :ivar_name
+
+    # @param name [Symbol, String] canonical field name
+    # @param type [Class<Types::Base>] the resolved type class
+    # @param type_instance [Types::Base, nil] optional pre-built instance —
+    #   used by the DSL for parameterized types (e.g. {Types::Nested}) where
+    #   +type.new+ wouldn't be enough to capture the parameterization. When
+    #   nil, +type.new+ is called.
+    # @param required [Boolean]
+    # @param default [Object, nil] literal default value, or a
+    #   parameterless callable (Proc/Lambda/Method) that returns one.
+    #   Callables are invoked once per instance during apply_defaults.
+    # @param coercion_policy [:keep_raw, :replace, :raise, nil] override
+    #   the class-level coercion policy for this one field; +nil+ means
+    #   "use whatever the class says"
+    # @param description [String, nil] human-readable description of the
+    #   field; for documentation purposes only
+    # @param rbs_type [String, nil] RBS type expression overriding the
+    #   derived one in generated signatures (see {#rbs_type})
+    # @param sensitive [Boolean] mask the value in {Base#inspect} (see {#sensitive?})
+    # @param options [Object, nil] extra keyword type/field options
+    #   forwarded to coerce (e.g. +format:+, +of_type:+, +round:+,
+    #   +values:+, +enum:+, +in:+)
+    def initialize(name:, type:, type_instance: nil, required: false, default: nil, coercion_policy: nil, description: nil, rbs_type: nil, sensitive: false, **options)
+      @name = name.to_sym
+      @setter_name = :"#{@name}="
+      @ivar_name = :"@#{@name}"
+      @type = type
+      @required = required
+      @default = default
+      @options = options.freeze
+      @type_instance = type_instance || type.new
+      @coercion_policy = coercion_policy
+      @description = description
+      @rbs_type = rbs_type
+      @sensitive = sensitive
+      freeze
+    end
+
+    # @return [Boolean]
+    def required?
+      @required
+    end
+
+    # Whether the field holds data that must not reach a log — a card
+    # number, a CVV, a token. {Base#inspect} (and so +pp+) renders
+    # {FieldStruct::FILTERED} in place of a non-nil value. Data paths —
+    # the reader, +attributes+, +to_h+, +as_json+, +to_json+, pattern
+    # matching — return the real value, so round-trips stay exact.
+    # Declared with the +sensitive:+ field option.
+    #
+    # @return [Boolean]
+    def sensitive?
+      @sensitive
+    end
+
+    # @return [String, nil] shorter alias of {#description}
+    alias desc description
+
+    # Concise one-line representation. Designed to be readable in IRB
+    # without dumping every ivar (the default Object#inspect is the
+    # reason +optional :x, :string+ in a console looks like a wall of
+    # text).
+    #
+    # @return [String]
+    def inspect
+      parts = [@name.inspect, type_repr]
+      parts << 'required' if @required
+      parts << 'sensitive' if @sensitive
+      parts << "default=#{@default.inspect}" unless @default.nil?
+      parts << "coercion_policy=#{@coercion_policy.inspect}" if @coercion_policy
+      parts << "description=#{@description.inspect}" if @description
+      parts << "rbs_type=#{@rbs_type.inspect}" if @rbs_type
+      @options.each { |key, value| parts << "#{key}=#{option_repr(value)}" }
+      "#<#{FieldStruct.inspect_namespace}::Field #{parts.join(" ")}>"
+    end
+
+    # Delegates pretty-print to {#inspect} so IRB / pp don't fall back
+    # to the default reflection-based output.
+    #
+    # @param pp [Object] a PP-shaped sink (responds to +#text+)
+    # @return [void]
+    def pretty_print(pp)
+      pp.text(inspect)
+    end
+
+    private
+
+    # @return [String] the type's short name, or +Nested(...)+ / +Union(...)+
+    def type_repr
+      base = @type.name.to_s.split('::').last
+      if @type <= FieldStruct::Types::Nested
+        "Nested(#{@type_instance.struct_class.name || "AnonymousFieldStruct"})"
+      elsif @type <= FieldStruct::Types::Union
+        members = @type_instance.member_types.map { |m| m.class.name.to_s.split('::').last }
+        "Union(#{members.join(" | ")})"
+      else
+        base
+      end
+    end
+
+    # Render an option's value in inspect output. Type-class values
+    # (e.g. +:of_type+ on an Array field) get their basename instead
+    # of the full +FieldStruct::Types::String+ class.inspect.
+    #
+    # @param value [Object, nil] an option value
+    # @return [String]
+    def option_repr(value)
+      case value
+      when ::Class
+        value.name.to_s.split('::').last
+      when FieldStruct::Types::Nested
+        "Nested(#{value.struct_class.name || "AnonymousFieldStruct"})"
+      when FieldStruct::Types::Base
+        value.class.name.to_s.split('::').last
+      # Spelled out rather than Hash#inspect, whose format changed in Ruby 3.4.
+      when ::Hash
+        "{#{value.map { |key, item| "#{key}: #{option_repr(item)}" }.join(", ")}}"
+      else
+        value.inspect
+      end
+    end
+  end
+end

data/lib/field_struct/metadata.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+module FieldStruct
+  # The per-class collection of {Field} declarations.
+  #
+  # Mutable while a class is being defined — the DSL adds fields as it
+  # encounters them — and queried thereafter by name or via iteration.
+  # Subclass inheritance is handled by {#merge}: a fresh child Metadata
+  # is seeded with the parent's fields, then accumulates its own; child
+  # declarations win on conflict.
+  class Metadata
+    include Enumerable
+
+    def initialize
+      @fields = {}
+      @serializations = {}
+      @reverse_serializations = {}
+    end
+
+    # @return [Hash{Symbol=>Hash{Symbol=>String}}] declared
+    #   external-name mappings keyed by format name. Each inner hash
+    #   maps an internal field name (Symbol) to its external name
+    #   (String). Fields not listed in an inner hash serialize under
+    #   their canonical name.
+    attr_reader :serializations
+
+    # @param field [Field]
+    # @return [self]
+    def add(field)
+      @fields[field.name] = field
+      self
+    end
+
+    # @param name [Symbol, String]
+    # @return [Field, nil]
+    def [](name)
+      @fields[name.to_sym]
+    end
+
+    # @return [Array<Symbol>] field names in insertion order
+    def names
+      @fields.keys
+    end
+
+    # Yields each {Field} in insertion order.
+    #
+    # @yield [field]
+    # @yieldparam field [Field]
+    # @return [Enumerator<Field>] when no block is given
+    def each(&block)
+      @fields.each_value(&block)
+    end
+
+    # A copy-pasteable schema view of the declared fields, keyed by field
+    # name. Each value is a plain Hash of primitives/strings (no live type
+    # objects), so the result reads cleanly in a console and is safe to
+    # `pp` or dump — handy for seeing a model's shape without reading its
+    # source. Option values that are classes or type instances are rendered
+    # as short names; a callable default shows as +"<callable>"+.
+    #
+    #   User.metadata.to_h
+    #   # => { name: { type: "String", ruby_type: "String", required: true,
+    #   #              default: nil, options: {}, description: nil }, ... }
+    #
+    # When a block is given this falls back to +Enumerable#to_h+ (mapping
+    # each {Field} to a pair), preserving existing callers.
+    #
+    # @return [Hash{Symbol=>Hash{Symbol=>Object, nil}}] field name → schema, or
+    #   the block-mapped pairs when a block is supplied
+    def to_h(&block)
+      return super if block
+
+      @fields.transform_values { |field| field_schema(field) }
+    end
+
+    # Record a serialization mapping for the named format. Repeats on
+    # the same format name replace the prior mapping (last-write-wins).
+    # The mapping is frozen on its way in.
+    #
+    # @param name [Symbol, String]
+    # @param mapping [Hash{Symbol=>String}]
+    # @return [self]
+    def add_serialization(name, mapping)
+      @serializations[name.to_sym] = mapping.freeze
+      self
+    end
+
+    # Look up the mapping for a format. Returns an empty hash when the
+    # format hasn't been declared — the implicit identity mapping that
+    # serializers fall back to.
+    #
+    # @param name [Symbol, String]
+    # @return [Hash{Symbol=>String}] frozen mapping (empty hash when undeclared)
+    def serialization(name)
+      @serializations[name.to_sym] || EMPTY_SERIALIZATION
+    end
+
+    # The reverse of {#serialization}: external name → field name, which
+    # {Base.from_json} needs on every call. Built once per mapping and reused
+    # while {#serialization} still returns that same frozen mapping, so any
+    # writer that installs a new one ({#add_serialization}, {#merge}, or a
+    # direct write to {#serializations}) is picked up on the next call.
+    #
+    # @api private
+    # @param name [Symbol, String]
+    # @return [Hash{String=>Symbol}] frozen; empty when the format is undeclared
+    def reverse_serialization(name)
+      key = name.to_sym
+      mapping = serialization(key)
+      cached = @reverse_serializations[key]
+      return cached.last if cached && cached.first.equal?(mapping)
+
+      reverse = mapping.each_with_object({}) { |(internal, external), out| out[external] = internal }.freeze
+      # A mapping that isn't frozen could change in place, so it isn't cached.
+      @reverse_serializations[key] = [mapping, reverse] if mapping.frozen?
+      reverse
+    end
+
+    # The identity mapping {#serialization} returns for an undeclared format.
+    # @return [Hash{Symbol=>String}]
+    EMPTY_SERIALIZATION = {}.freeze
+    private_constant :EMPTY_SERIALIZATION
+
+    # Copy fields and serializations from +parent+ into self, leaving
+    # already-declared entries untouched (child wins). Order: existing
+    # self fields stay where they are; parent fields are appended in
+    # iteration order if not present.
+    #
+    # @param parent [Metadata]
+    # @return [self]
+    def merge(parent)
+      parent.each do |field|
+        @fields[field.name] = field unless @fields.key?(field.name)
+      end
+      parent.serializations.each do |name, mapping|
+        @serializations[name] = mapping unless @serializations.key?(name)
+      end
+      self
+    end
+
+    # Concise one-line representation. Lists the declared field names
+    # and, when present, the declared serialization formats — without
+    # dumping the underlying ivar hashes.
+    #
+    # @return [String]
+    def inspect
+      return "#<#{FieldStruct.inspect_namespace}::Metadata empty>" if @fields.empty?
+
+      parts = ["fields=#{@fields.keys.inspect}"]
+      parts << "serializations=#{@serializations.keys.inspect}" unless @serializations.empty?
+      "#<#{FieldStruct.inspect_namespace}::Metadata #{parts.join(" ")}>"
+    end
+
+    # Multi-line representation suitable for IRB / pp. Renders each
+    # field on its own indented line using {Field#inspect}, with the
+    # closing +>+ on its own line.
+    #
+    # @param pp [Object] a PP-shaped sink (responds to +#text+)
+    # @return [void]
+    def pretty_print(pp)
+      if @fields.empty?
+        pp.text(inspect)
+        return
+      end
+
+      pp.text("#<#{FieldStruct.inspect_namespace}::Metadata")
+      @fields.each_value do |field|
+        pp.text("\n  ")
+        pp.text(field.inspect)
+      end
+      pp.text("\n  serializations=#{@serializations.keys.inspect}") unless @serializations.empty?
+      pp.text("\n>")
+    end
+
+    # Human/agent-readable summary of the declared fields: one line each
+    # with the field's type, required-ness, and the native options its type
+    # accepts (with value shapes, required options starred, and any presets).
+    # Answers "what can I put here?" without reading source. For the
+    # structured form use {#to_h}; for a class-titled version use
+    # {Base.describe}.
+    #
+    #   name (String, required) — accepts format (Regexp | Symbol), enum (Array)
+    #
+    # @return [String]
+    def describe
+      return '(no fields)' if @fields.empty?
+
+      @fields.each_value.map { |field| describe_field(field) }.join("\n")
+    end
+
+    private
+
+    # @param field [Field]
+    # @return [String] one +describe+ line for a field
+    def describe_field(field)
+      flags = [short_name(field.type), field.required? ? 'required' : 'optional']
+      flags << 'sensitive' if field.sensitive?
+      label = "  #{field.name} (#{flags.join(", ")})"
+      parts = [label, declared_options_summary(field), accepts_summary(field.type), element_accepts_summary(field)].compact
+
+      parts.join(' — ')
+    end
+
+    # What this field actually declares, as written.
+    #
+    # Without this, +describe+ answered only "what COULD go in this field" —
+    # the type's option vocabulary — and a field declaring
+    # +format: :iso8601, enum: %w[USD EUR]+ rendered identically to one
+    # declaring nothing at all. The option schema belongs to the type; this
+    # belongs to the field.
+    #
+    # @param field [Field]
+    # @return [String, nil] +nil+ when the field declares no options
+    def declared_options_summary(field)
+      # Every temporal field carries `format: nil` from apply_default_format,
+      # so nils are dropped rather than rendered as a declaration that isn't one.
+      declared = field.options.compact
+      return nil if declared.empty?
+
+      declared.map { |key, value| "#{key}: #{declared_option_repr(value)}" }.join(', ')
+    end
+
+    # @return [String] a declared option value, rendered for a human. Type
+    #   values (an Array field's +of_type:+) show their bare type name rather
+    #   than a quoted string, so the line reads like the declaration it
+    #   describes.
+    # @param value [Object, nil] a declared option value
+    def declared_option_repr(value)
+      case value
+      when FieldStruct::Types::Nested then "Nested(#{short_name(value.struct_class)})"
+      when FieldStruct::Types::Base then short_name(value.class)
+      when ::Class then short_name(value)
+      # Spelled out rather than Hash#inspect, whose format changed in Ruby 3.4.
+      when ::Hash then "{#{value.map { |key, item| "#{key}: #{declared_option_repr(item)}" }.join(", ")}}"
+      else value.inspect
+      end
+    end
+
+    # What an array field's +element:+ may hold — the names of its element
+    # type's native options — so the line answers "what can I pass to each
+    # element" too.
+    #
+    # @param field [Field]
+    # @return [String, nil] +nil+ for a non-array field, or an element type
+    #   with no options (a nested struct)
+    def element_accepts_summary(field)
+      return nil unless field.type <= FieldStruct::Types::Array
+
+      # Names only: the shapes are the element type's own (its
+      # +option_schema+), and repeating them doubled every array line.
+      element_class = FieldStruct::Types::Array.element_class(field.options[:of_type])
+      return nil unless element_class.respond_to?(:option_schema)
+
+      names = element_class.option_schema.keys
+      names.empty? ? nil : "element accepts #{names.join(", ")}"
+    end
+
+    # @return [String, nil] the type's native option vocabulary, or +nil+ when
+    #   the type declares none
+    # @param type_class [Class<Types::Base>]
+    def accepts_summary(type_class)
+      accepts = native_options_summary(type_class)
+      accepts.empty? ? nil : "accepts #{accepts}"
+    end
+
+    # @return [String] the type's native options as +name(shapes)+, required
+    #   ones starred, presets appended — empty when the type has none
+    # @param type_class [Class<Types::Base>]
+    def native_options_summary(type_class)
+      return '' unless type_class.respond_to?(:option_schema)
+
+      type_class.option_schema.map do |name, descriptor|
+        shapes = descriptor[:type].map { |klass| short_name(klass) }.join(' | ')
+        star = descriptor[:required] ? '*' : ''
+        presets = descriptor[:presets].empty? ? '' : "; presets: #{descriptor[:presets].join(", ")}"
+        "#{name}#{star} (#{shapes}#{presets})"
+      end.join(', ')
+    end
+
+    # Render one field as a primitive-only schema Hash for {#to_h}.
+    #
+    # @param field [Field]
+    # @return [Hash{Symbol=>Object, nil}]
+    def field_schema(field)
+      schema = {
+        type: short_name(field.type),
+        ruby_type: ruby_type_repr(field.type_instance.ruby_type),
+        required: field.required?,
+        default: schema_value(field.default),
+        options: field.options.transform_values { |value| schema_value(value) },
+        description: field.description
+      }
+      # Only when set, so the schema of a field without one is unchanged.
+      schema[:rbs_type] = field.rbs_type if field.rbs_type
+      schema[:sensitive] = true if field.sensitive?
+      schema
+    end
+
+    # A single class, or +A | B+ for a multi-class ruby_type (boolean, union).
+    #
+    # @param ruby_type [Class, Array<Class>] a type's {Types::Base#ruby_type}
+    # @return [String]
+    def ruby_type_repr(ruby_type)
+      Array(ruby_type).map(&:name).join(' | ')
+    end
+
+    # Reduce an option/default value to something printable: short class
+    # names for type references, +"<callable>"+ for procs, recursion into
+    # Array/Hash, everything else as-is.
+    #
+    # @param value [Object, nil] an option or default value
+    # @return [Object, nil]
+    def schema_value(value)
+      case value
+      when nil, true, false, ::Numeric, ::String, ::Symbol, ::Regexp, ::Range then value
+      when ::Class then short_name(value)
+      when FieldStruct::Types::Base then short_name(value.class)
+      when ::Array then value.map { |element| schema_value(element) }
+      when ::Hash then value.transform_values { |element| schema_value(element) }
+      else
+        value.respond_to?(:call) ? '<callable>' : value
+      end
+    end
+
+    # @param klass [Module]
+    # @return [String] the last segment of the class name
+    def short_name(klass)
+      klass.name.to_s.split('::').last
+    end
+  end
+end