structure 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74f52e94d4ffd40ad55e291a4ab72c108af572be936ee2d1571fef47699af2cb
-  data.tar.gz: d2ef8dee35e2ea236237d1c34c68bc6877039145553f7e1b16729ea84e3778c4
+  metadata.gz: 0d49fdb007e1c1690e686dc7c17498fd905b8e100c8dcf8fe3b374c99ec18c14
+  data.tar.gz: 3dbdc1a4e9ac4e6e70332084bda5612b4b17dc74a63a28e0eb084a2f49d440bb
 SHA512:
-  metadata.gz: f0c4192ddde552c7cd4a583aca9bdad31aeb64dc039680e965944696ee7648cc9a423017ab8cea5546c708ae72b7920c21fb2c96e74442932f24a3a85faa6b81
-  data.tar.gz: 03d4ea5fda959cd3bcd60b79a323b8dbfaeb5792c22b809179b7f84f76aab36845e7dbcd2f30567cf7922eea9995997cfb730cd69e8dd726cebded2bd076f540
+  metadata.gz: 9d7c579f4e71000c4cabeaa4bd95deb3c01763b0ab5e426fb7544da65e7617a5e8ac7d32c7a3079f690a55c0021a57d97646732d516a25796cbc8999dbb6630a
+  data.tar.gz: '02791f8b7a9372c583839e35c7c20c6bb7ec03626256f92f9cda2ef11c5188d541f0f3b073a053d7ccf152da4a47c4af32eeb65b2e68a92ecc00e8494174ba7e'

data/lib/structure/builder.rb

@@ -14,6 +14,7 @@ module Structure
       @defaults = {}
       @types = {}
       @optional = Set.new
+      @non_nullable = Set.new
     end
 
     # DSL method for defining attributes with optional type coercion
@@ -22,6 +23,7 @@ module Structure
     # @param type [Class, Symbol, Array, nil] Type for coercion (e.g., String, :boolean, [String])
     # @param from [String, nil] Source key in the data hash (defaults to name.to_s)
     # @param default [Object, nil] Default value if attribute is missing
+    # @param null [Boolean] Whether nil values are allowed (default: true)
     # @yield [value] Block for custom transformation
     # @raise [ArgumentError] If both type and block are provided
     #
@@ -35,12 +37,16 @@ module Structure
     #   attribute :price do |value|
     #     Money.new(value["amount"], value["currency"])
     #   end
-    def attribute(name, type = nil, from: nil, default: nil, &block)
-      mappings[name] = from || name.to_s
+    #
+    # @example Non-nullable attribute
+    #   attribute :id, String, null: false
+    def attribute(name, type = nil, from: nil, default: nil, null: true, &block)
+      mappings[name] = (from || name).to_s
       defaults[name] = default unless default.nil?
+      @non_nullable.add(name) unless null
 
       if type && block
-        raise ArgumentError, "Cannot specify both type and block for :#{name}"
+        raise ArgumentError, "cannot specify both type and block for :#{name}"
       else
         types[name] = type || block
       end
@@ -52,6 +58,7 @@ module Structure
     # @param type [Class, Symbol, Array, nil] Type for coercion (e.g., String, :boolean, [String])
     # @param from [String, nil] Source key in the data hash (defaults to name.to_s)
     # @param default [Object, nil] Default value if attribute is missing
+    # @param null [Boolean] Whether nil values are allowed (default: true)
     # @yield [value] Block for custom transformation
     # @raise [ArgumentError] If both type and block are provided
     #
@@ -60,8 +67,11 @@ module Structure
     #
     # @example Optional with default
     #   attribute? :status, String, default: "pending"
-    def attribute?(name, type = nil, from: nil, default: nil, &block)
-      attribute(name, type, from: from, default: default, &block)
+    #
+    # @example Optional but non-nullable when present
+    #   attribute? :name, String, null: false
+    def attribute?(name, type = nil, from: nil, default: nil, null: true, &block)
+      attribute(name, type, from: from, default: default, null: null, &block)
       @optional.add(name)
     end
 
@@ -87,9 +97,17 @@ module Structure
     # @api private
     def required = attributes - optional
 
+    # @api private
+    def non_nullable = @non_nullable.to_a
+
     # @api private
     def coercions(context = nil)
-      @types.transform_values { |type| Types.coerce(type, context) }
+      @types.to_h do |attr, type|
+        coercion = Types.coerce(type, context)
+        [attr, coercion]
+      rescue ArgumentError => e
+        raise ArgumentError, "#{e.message} for :#{attr}"
+      end
     end
 
     # @api private

data/lib/structure/rbs.rb

@@ -5,10 +5,13 @@ require "pathname"
 
 module Structure
   # Generates RBS type signatures for Structure classes
-  #
-  # Note: Custom methods defined in Structure blocks are not included and must be manually added to RBS files. This is
-  # consistent with how Ruby's RBS tooling handles Data classes.
   module RBS
+    # @type const EMPTY_CUSTOM_METHODS: { instance: Array[untyped], singleton: Array[untyped] }
+    empty_instance = _ = [] #: Array[untyped]
+    empty_singleton = _ = [] #: Array[untyped]
+    EMPTY_CUSTOM_METHODS = { instance: empty_instance, singleton: empty_singleton }.freeze
+    private_constant :EMPTY_CUSTOM_METHODS
+
     class << self
       def emit(klass)
         return unless klass < Data
@@ -20,8 +23,12 @@ module Structure
         meta = klass.respond_to?(:__structure_meta__) ? klass.__structure_meta__ : {}
 
         attributes = meta[:mappings] ? meta[:mappings].keys : klass.members
-        types = meta.fetch(:types, {}) # steep:ignore
-        required = meta.fetch(:required, attributes) # steep:ignore
+        # @type var types: Hash[Symbol, untyped]
+        default_types = _ = {} #: Hash[Symbol, untyped]
+        types = meta.fetch(:types, default_types)
+        # @type var required: Array[Symbol]
+        required = meta.fetch(:required, attributes)
+        custom_methods = meta.fetch(:custom_methods, EMPTY_CUSTOM_METHODS)
 
         emit_rbs_content(
           class_name:,
@@ -29,6 +36,7 @@ module Structure
           types:,
           required:,
           has_structure_modules: meta.any?,
+          custom_methods:,
         )
       end
 
@@ -53,7 +61,7 @@ module Structure
 
       private
 
-      def emit_rbs_content(class_name:, attributes:, types:, required:, has_structure_modules:)
+      def emit_rbs_content(class_name:, attributes:, types:, required:, has_structure_modules:, custom_methods:)
         # @type var lines: Array[String]
         lines = []
         lines << "class #{class_name} < Data"
@@ -87,48 +95,127 @@ module Structure
             }.join(", ") + " }"
           end
 
-          lines << "  def self.new: (#{keyword_params}) -> #{class_name}"
-          lines << "              | (#{positional_params}) -> #{class_name}"
-          lines << ""
-          lines << "  def self.[]: (#{keyword_params}) -> #{class_name}"
-          lines << "             | (#{positional_params}) -> #{class_name}"
-          lines << ""
+          # Build singleton methods list
+          # Note: `new` and `[]` are kept at top (RBS::Sorter convention)
+          special_singleton_methods = [
+            {
+              name: "new",
+              lines: [
+                "  def self.new: (#{keyword_params}) -> #{class_name}",
+                "              | (#{positional_params}) -> #{class_name}",
+              ],
+            },
+            {
+              name: "[]",
+              lines: [
+                "  def self.[]: (#{keyword_params}) -> #{class_name}",
+                "             | (#{positional_params}) -> #{class_name}",
+              ],
+            },
+          ]
 
-          # Generate members tuple type
+          # Regular singleton methods (to be sorted)
+          # @type var singleton_methods_list: Array[{ name: String, lines: Array[String] }]
+          singleton_methods_list = []
+
+          # Add custom singleton methods
+          # @type var custom_singleton: Array[untyped]
+          default_singleton = _ = [] #: Array[untyped]
+          custom_singleton = custom_methods.fetch(:singleton, default_singleton)
+          custom_singleton.each do |method_meta|
+            singleton_methods_list << {
+              name: method_meta[:name].to_s,
+              lines: [format_method_signature(method_meta, singleton: true)],
+            }
+          end
+
+          # Add standard singleton methods
           members_tuple = attributes.map { |attr| ":#{attr}" }.join(", ")
-          lines << "  def self.members: () -> [ #{members_tuple} ]"
-          lines << ""
+          singleton_methods_list << {
+            name: "members",
+            lines: ["  def self.members: () -> [ #{members_tuple} ]"],
+          }
 
-          # Generate parse method signatures
-          if needs_parse_data
-            lines << "  def self.parse: (?parse_data data) -> #{class_name}"
-            lines << "                | (?Hash[String, untyped] data) -> #{class_name}"
+          singleton_methods_list << if needs_parse_data
+            {
+              name: "parse",
+              lines: [
+                "  def self.parse: (?parse_data data) -> #{class_name}",
+                "                | (?Hash[String, untyped] data) -> #{class_name}",
+              ],
+            }
           else
-            # Remove optional parentheses to match RBS::Sorter style
-            lines << "  def self.parse: (?Hash[String | Symbol, untyped], **untyped) -> #{class_name}"
+            {
+              name: "parse",
+              lines: ["  def self.parse: (?Hash[String | Symbol, untyped], **untyped) -> #{class_name}"],
+            }
           end
+
+          # Emit special singleton methods first (new, [])
+          special_singleton_methods.each do |method|
+            # @type var method_lines: Array[String]
+            method_lines = method[:lines]
+            method_lines.each { |line| lines << line }
+          end
+
+          # Sort and emit other singleton methods
+          singleton_methods_list.sort_by { |m| m[:name] }.each do |method|
+            lines << "" # Blank line before each method group
+            # @type var method_lines: Array[String]
+            method_lines = method[:lines]
+            method_lines.each { |line| lines << line }
+          end
+
           lines << ""
 
           # Sort attr_reader lines alphabetically (RBS::Sorter does this)
           attributes.sort.each do |attr|
             lines << "  attr_reader #{attr}: #{rbs_types[attr]}"
           end
+          lines << ""
+
+          # Build instance methods list (standard + custom), then sort
+          # @type var instance_methods_list: Array[{ name: String, lines: Array[String] }]
+          instance_methods_list = []
 
           # Add boolean predicates
           boolean_predicates = types.sort.select { |attr, type| type == :boolean && !attr.to_s.end_with?("?") }
-          unless boolean_predicates.empty?
-            lines << ""
-            boolean_predicates.each do |attr, _type|
-              lines << "  def #{attr}?: () -> bool"
-            end
+          boolean_predicates.each do |attr, _type|
+            instance_methods_list << {
+              name: "#{attr}?",
+              lines: ["  def #{attr}?: () -> bool"],
+            }
           end
 
-          # Instance members method comes after attr_readers and predicates
-          lines << "  def members: () -> [ #{members_tuple} ]"
-          lines << ""
+          # Add custom instance methods
+          # @type var custom_instance: Array[untyped]
+          default_instance = _ = [] #: Array[untyped]
+          custom_instance = custom_methods.fetch(:instance, default_instance)
+          custom_instance.each do |method_meta|
+            instance_methods_list << {
+              name: method_meta[:name].to_s,
+              lines: [format_method_signature(method_meta, singleton: false)],
+            }
+          end
+
+          # Add standard instance methods
+          instance_methods_list << {
+            name: "members",
+            lines: ["  def members: () -> [ #{members_tuple} ]"],
+          }
 
           hash_type = attributes.map { |attr| "#{attr}: #{rbs_types[attr]}" }.join(", ")
-          lines << "  def to_h: () -> { #{hash_type} }"
+          instance_methods_list << {
+            name: "to_h",
+            lines: ["  def to_h: () -> { #{hash_type} }"],
+          }
+
+          # Sort and emit instance methods
+          instance_methods_list.sort_by { |m| m[:name] }.each do |method|
+            # @type var method_lines: Array[String]
+            method_lines = method[:lines]
+            method_lines.each { |line| lines << line }
+          end
         end
 
         lines << "end"
@@ -183,6 +270,54 @@ module Structure
           "untyped"
         end
       end
+
+      def format_method_signature(method_meta, singleton:)
+        name = method_meta.fetch(:name)
+        parameters = method_meta.fetch(:parameters, [])
+
+        params_str, block_str = build_parameters_fragment(parameters)
+
+        method_prefix = singleton ? "self." : ""
+        signature = "  def #{method_prefix}#{name}: #{params_str}"
+        signature += " #{block_str}" if block_str
+        signature + " -> untyped"
+      end
+
+      def build_parameters_fragment(parameters)
+        # @type var parts: Array[String]
+        parts = []
+        block_required = false
+
+        parameters.each do |kind, param_name|
+          case kind
+          when :req
+            parts << "untyped"
+          when :opt
+            parts << "?untyped"
+          when :rest
+            parts << "*untyped"
+          when :keyreq
+            key_name = param_name || :arg
+            parts << "#{key_name}: untyped"
+          when :key
+            key_name = param_name || :arg
+            parts << "?#{key_name}: untyped"
+          when :keyrest
+            parts << "**untyped"
+          when :block
+            block_required = true
+          else
+            parts << "untyped"
+          end
+        end
+
+        params_str = "(#{parts.join(", ")})"
+        params_str = "()" if parts.empty?
+
+        block_str = block_required ? "?{ (*untyped, **untyped) -> untyped }" : nil
+
+        [params_str, block_str]
+      end
     end
   end
 end

data/lib/structure/types.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Structure
   # Type coercion methods for converting values to specific types
   module Types
     class << self
       # Rails-style boolean truthy values
       # Reference: https://api.rubyonrails.org/classes/ActiveModel/Type/Boolean.html
-      BOOLEAN_TRUTHY = [true, 1, "1", "t", "T", "true", "TRUE", "on", "ON"].freeze
+      BOOLEAN_TRUTHY = Set.new([true, 1, "1", "t", "T", "true", "TRUE", "on", "ON"]).freeze
       private_constant :BOOLEAN_TRUTHY
 
       # Main factory method for creating type coercers
@@ -58,7 +60,7 @@ module Structure
         when String
           lazy_class(type, context)
         else
-          raise ArgumentError, "Cannot specify #{type.inspect} as type"
+          raise ArgumentError, "cannot specify #{type.inspect} as type"
         end
       end
 
@@ -93,12 +95,15 @@ module Structure
             value.map { |element| context.parse(element) }
           end
         when String
+          resolved_class = nil
+
           lambda do |value|
             unless value.respond_to?(:map)
               raise TypeError, "can't convert #{value.class} into Array"
             end
 
-            resolved_class = resolve_class(element_type, context)
+            resolved_class ||= resolve_class(element_type, context)
+            # @type var resolved_class: untyped
             value.map { |element| resolved_class.parse(element) }
           end
         else

data/lib/structure/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Structure
-  VERSION = "4.1.0"
+  VERSION = "4.2.0"
 end

data/lib/structure.rb

@@ -4,6 +4,9 @@ require "structure/builder"
 
 # A library for parsing data into immutable Ruby Data objects with type coercion
 module Structure
+  TO_H_CHECKER = ->(x) { x.respond_to?(:to_h) && x }
+  private_constant :TO_H_CHECKER
+
   class << self
     # Creates a new Data class with attribute definitions and type coercion
     #
@@ -21,13 +24,18 @@ module Structure
     #   person.age  # => 30
     def new(&block)
       builder = Builder.new
-      builder.instance_eval(&block) if block
+      builder.instance_eval(&block) if block # steep:ignore
 
       # @type var klass: untyped
       klass = Data.define(*builder.attributes)
 
+      custom_methods_metadata = { instance: [], singleton: [] }.freeze # steep:ignore
+
       # Enable custom method definitions by evaluating block on the class
       if block
+        before_instance_methods = klass.instance_methods(false)
+        before_singleton_methods = klass.singleton_methods(false)
+
         # Provide temporary dummy DSL methods to prevent NoMethodError during class_eval
         klass.define_singleton_method(:attribute) { |*args, **kwargs, &blk| }
         klass.define_singleton_method(:attribute?) { |*args, **kwargs, &blk| }
@@ -40,6 +48,36 @@ module Structure
         klass.singleton_class.send(:remove_method, :attribute)
         klass.singleton_class.send(:remove_method, :attribute?)
         klass.singleton_class.send(:remove_method, :after_parse)
+
+        after_instance_methods = klass.instance_methods(false)
+        after_singleton_methods = klass.singleton_methods(false)
+
+        newly_defined_instance_methods = after_instance_methods - before_instance_methods
+        newly_defined_singleton_methods = after_singleton_methods - before_singleton_methods
+
+        instance_method_metadata = newly_defined_instance_methods.filter_map do |name|
+          next unless klass.public_method_defined?(name)
+
+          {
+            name: name,
+            parameters: klass.instance_method(name).parameters,
+          }.freeze
+        end
+
+        singleton_class = klass.singleton_class
+        singleton_method_metadata = newly_defined_singleton_methods.filter_map do |name|
+          next unless singleton_class.public_method_defined?(name)
+
+          {
+            name: name,
+            parameters: singleton_class.instance_method(name).parameters,
+          }.freeze
+        end
+
+        custom_methods_metadata = {
+          instance: instance_method_metadata.freeze,
+          singleton: singleton_method_metadata.freeze,
+        }.freeze
       end
 
       # Override initialize to make optional attributes truly optional
@@ -48,12 +86,14 @@ module Structure
         klass.class_eval do
           alias_method(:__data_initialize__, :initialize)
 
-          define_method(:initialize) do |**kwargs| # steep:ignore
+          # steep:ignore:start
+          define_method(:initialize) do |**kwargs|
             optional_attrs.each do |attr|
               kwargs[attr] = nil unless kwargs.key?(attr)
             end
-            __data_initialize__(**kwargs) # steep:ignore
+            __data_initialize__(**kwargs)
           end
+          # steep:ignore:end
         end
       end
 
@@ -69,6 +109,8 @@ module Structure
         coercions: builder.coercions(klass),
         after_parse: builder.after_parse_callback,
         required: builder.required,
+        non_nullable: builder.non_nullable,
+        custom_methods: custom_methods_metadata,
       }.freeze
       klass.instance_variable_set(:@__structure_meta__, meta)
       klass.singleton_class.attr_reader(:__structure_meta__)
@@ -79,7 +121,7 @@ module Structure
           v = public_send(m)
           value = case v
           when Array then v.map { |x| x.respond_to?(:to_h) && x ? x.to_h : x }
-          when ->(x) { x.respond_to?(:to_h) && x } then v.to_h
+          when TO_H_CHECKER then v.to_h
           else v
           end
           [m, value]
@@ -100,11 +142,13 @@ module Structure
 
         overrides&.each { |k, v| data[k.to_s] = v }
 
-        final       = {}
-        mappings    = __structure_meta__[:mappings]
-        defaults    = __structure_meta__[:defaults]
-        after_parse = __structure_meta__[:after_parse]
-        required    = __structure_meta__[:required]
+        final        = {}
+        mappings     = __structure_meta__[:mappings]
+        defaults     = __structure_meta__[:defaults]
+        coercions    = __structure_meta__[:coercions]
+        after_parse  = __structure_meta__[:after_parse]
+        required     = __structure_meta__[:required]
+        non_nullable = __structure_meta__[:non_nullable]
 
         # Check for missing required attributes
         required.each do |attr|
@@ -115,6 +159,8 @@ module Structure
         end
 
         mappings.each do |attr, from|
+          key_present = data.key?(from) || data.key?(from.to_sym)
+
           value = data.fetch(from) do
             data.fetch(from.to_sym) do
               defaults[attr]
@@ -122,10 +168,16 @@ module Structure
           end
 
           if value
-            coercion = __structure_meta__[:coercions][attr]
+            coercion = coercions[attr]
             value = coercion.call(value) if coercion
           end
 
+          # Check non-null constraint after coercion
+          # Only check if key was present in data OR attribute has an explicit default
+          if value.nil? && non_nullable.include?(attr) && (key_present || defaults.key?(attr))
+            raise ArgumentError, "cannot be null: :#{attr}"
+          end
+
           final[attr] = value
         end
 

data/sig/structure/builder.rbs

@@ -5,12 +5,13 @@ module Structure
     @defaults: Hash[Symbol, untyped]
     @after_parse_callback: Proc?
     @optional: Set[Symbol]
+    @non_nullable: Set[Symbol]
 
-    def attribute: (Symbol name, untyped type, ?from: String?, ?default: untyped) ?{ (untyped) -> untyped } -> void
-                 | (Symbol name, ?from: String, ?default: untyped) ?{ (untyped) -> untyped } -> void
+    def attribute: (Symbol name, untyped type, ?from: String | Symbol | nil, ?default: untyped, ?null: bool) ?{ (untyped) -> untyped } -> void
+                 | (Symbol name, ?from: String | Symbol | nil, ?default: untyped, ?null: bool) ?{ (untyped) -> untyped } -> void
 
-    def attribute?: (Symbol name, untyped type, ?from: String?, ?default: untyped) ?{ (untyped) -> untyped } -> void
-                  | (Symbol name, ?from: String, ?default: untyped) ?{ (untyped) -> untyped } -> void
+    def attribute?: (Symbol name, untyped type, ?from: String | Symbol | nil, ?default: untyped, ?null: bool) ?{ (untyped) -> untyped } -> void
+                  | (Symbol name, ?from: String | Symbol | nil, ?default: untyped, ?null: bool) ?{ (untyped) -> untyped } -> void
 
     def after_parse: () { (Data) -> void } -> void
 
@@ -22,6 +23,10 @@ module Structure
     def predicate_methods: () -> Hash[Symbol, Symbol]
     def optional: () -> Array[Symbol]
     def required: () -> Array[Symbol]
+    def non_nullable: () -> Array[Symbol]
     def after_parse_callback: () -> (Proc | nil)
+
+    def method_missing: (Symbol, *untyped, **untyped) ?{ (*untyped, **untyped) -> untyped } -> untyped
+    def respond_to_missing?: (Symbol, bool) -> bool
   end
 end

data/sig/structure/rbs.rbs

@@ -1,10 +1,14 @@
 module Structure
   module RBS
+    EMPTY_CUSTOM_METHODS: { instance: Array[untyped], singleton: Array[untyped] }
+
     def self.emit: (untyped klass) -> String?
     def self.write: (untyped klass, ?dir: String) -> String?
 
-    private def self.emit_rbs_content: (class_name: String, attributes: Array[Symbol], types: Hash[Symbol, untyped], required: Array[Symbol], has_structure_modules: bool) -> String
+    private def self.emit_rbs_content: (class_name: String, attributes: Array[Symbol], types: Hash[Symbol, untyped], required: Array[Symbol], has_structure_modules: bool, custom_methods: untyped) -> String
     private def self.parse_data_type: (untyped type, String class_name) -> String
     private def self.map_type_to_rbs: (untyped type, String class_name) -> String
+    private def self.format_method_signature: (Hash[Symbol, untyped] method_meta, singleton: bool) -> String
+    private def self.build_parameters_fragment: (Array[[Symbol, untyped]] parameters) -> [String, String?]
   end
 end

data/sig/structure/types.rbs

@@ -4,7 +4,7 @@ module Structure
       def parse: (untyped) -> untyped
     end
 
-    BOOLEAN_TRUTHY: Array[untyped]
+    BOOLEAN_TRUTHY: Set[untyped]
 
     self.@boolean: Proc
     self.@kernel_cache: Hash[untyped, Proc]

data/sig/structure.rbs

@@ -1,4 +1,6 @@
 module Structure
+  TO_H_CHECKER: Proc
+
   interface _StructuredDataClass
     def __structure_meta__: () -> {
       types: Hash[Symbol, untyped],
@@ -10,5 +12,7 @@ module Structure
     }
   end
 
-  def self.new: () ?{ (Structure::Builder) [self: Structure::Builder] -> void } -> untyped
+  # Block evaluated twice: first for DSL methods (attribute calls), then for custom methods
+  # Context set to Builder so DSL methods are recognized
+  def self.new: () ?{ () [self: Structure::Builder] -> void } -> untyped
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: structure
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.2.0
 platform: ruby
 authors:
 - Hakan Ensari