structure 3.6.3 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ecf2906322a2c0abaa86ab756c7154139788867b214ee5b30a071adf5e044ff
-  data.tar.gz: c36c7b4dfc5656a74b056c72af11ab478fc97886a1638312dd389d252e1977b3
+  metadata.gz: 2306964e18c5a78a2241c8c42071fd0a1921fa8c7c54cf210b0825b20607cfca
+  data.tar.gz: c43cf42996e715fe5c1ca1b57bf91ee411405f188382b2d10c0b593a66e90a6f
 SHA512:
-  metadata.gz: f6bcd31e925af5a25bb65b9ee1b2c4eff4654b7fbce6e7110d3c89195744b5ed7f3564a33dcf0b0cf19a373df315d955637388ccad8f6fa19aa394b21234e1d5
-  data.tar.gz: 3707eb84b1b0e702f4e13cf90b9048a3858ed71b07e399d969db4e4e36523fa4e9860c38fbe0d33a4b11336fb2b9f7389d136e80fa4ed280cd0301297102de56
+  metadata.gz: 314242bf300d7ec09e1755647d4a8fef224eb2c64fc0b6d945be386b7af008c22146e80993f1e753f1df9cc5b37841242b7ab4a14d71cde42732952e288fc196
+  data.tar.gz: 72dcc21770b4f57b67fd64b8ad69695f02d0a55b2622717f63795b8da32aa8b45cd61db146b2e2c4dc02683588ca74dba831437652afaed9bb25fc159195d0b5

data/lib/structure/builder.rb

@@ -5,12 +5,15 @@ require "structure/types"
 module Structure
   # Builder class for accumulating attribute definitions
   class Builder
-    attr_reader :mappings, :types, :defaults, :after_parse_callback
+    # @api private
+    attr_reader :mappings, :defaults, :types, :after_parse_callback
 
+    # @api private
     def initialize
       @mappings = {}
-      @types = {}
       @defaults = {}
+      @types = {}
+      @optional = Set.new
     end
 
     # DSL method for defining attributes with optional type coercion
@@ -43,6 +46,25 @@ module Structure
       end
     end
 
+    # DSL method for defining optional attributes (key can be missing from input hash)
+    #
+    # @param name [Symbol] The attribute name
+    # @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
+    # @yield [value] Block for custom transformation
+    # @raise [ArgumentError] If both type and block are provided
+    #
+    # @example Optional attribute
+    #   attribute? :age, Integer
+    #
+    # @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)
+      @optional.add(name)
+    end
+
     # Defines a callback to run after parsing
     #
     # @yield [instance] Block that receives the parsed instance
@@ -56,14 +78,21 @@ module Structure
       @after_parse_callback = block
     end
 
-    def attributes
-      @mappings.keys
-    end
+    # @api private
+    def attributes = @mappings.keys
+
+    # @api private
+    def optional = @optional.to_a
+
+    # @api private
+    def required = attributes - optional
 
-    def coercions(context_class = nil)
-      @types.transform_values { |type| Types.coerce(type, context_class) }
+    # @api private
+    def coercions(context = nil)
+      @types.transform_values { |type| Types.coerce(type, context) }
     end
 
+    # @api private
     def predicate_methods
       @types.filter_map do |name, type|
         if type == :boolean

data/lib/structure/rbs.rb

@@ -15,10 +15,15 @@ module Structure
         # @type var meta: Hash[Symbol, untyped]
         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
+
         emit_rbs_content(
-          class_name: class_name,
-          attributes: meta.fetch(:attributes, klass.members),
-          types: meta.fetch(:types, {}), # steep:ignore
+          class_name:,
+          attributes:,
+          types:,
+          required:,
           has_structure_modules: meta.any?,
         )
       end
@@ -44,7 +49,7 @@ module Structure
 
       private
 
-      def emit_rbs_content(class_name:, attributes:, types:, has_structure_modules:)
+      def emit_rbs_content(class_name:, attributes:, types:, required:, has_structure_modules:)
         # @type var lines: Array[String]
         lines = []
         lines << "class #{class_name} < Data"
@@ -58,7 +63,11 @@ module Structure
             [attr, rbs_type != "untyped" ? "#{rbs_type}?" : rbs_type]
           end.to_h
 
-          keyword_params = attributes.map { |attr| "#{attr}: #{rbs_types[attr]}" }.join(", ")
+          # Mark optional attributes with ? prefix in keyword params
+          keyword_params = attributes.map do |attr|
+            prefix = required.include?(attr) ? "" : "?"
+            "#{prefix}#{attr}: #{rbs_types[attr]}"
+          end.join(", ")
           positional_params = attributes.map { |attr| rbs_types[attr] }.join(", ")
 
           lines << "  def self.new: (#{keyword_params}) -> #{class_name}"

data/lib/structure/types.rb

@@ -11,130 +11,98 @@ module Structure
 
       # Main factory method for creating type coercers
       #
-      # @param type [Class, Symbol, Array, String] Type specification
-      # @return [Proc, Object] Coercion proc or the type itself if no coercion available
+      # @param type [Class, Symbol, Array, String, nil] Type specification
+      # @param context [Class, nil] Context class for lazy-loading and self-referential types
+      # @return [Proc, nil] Coercion proc or nil if no coercion needed
+      # @raise [ArgumentError] If type is a Hash instance (typed hashes not yet supported) or unsupported type
       #
       # @example Boolean type
       #   coerce(:boolean) # => boolean proc
       #
+      # @example Self-referential types
+      #   coerce(:self) # => proc that calls context.parse
+      #
       # @example Kernel types
       #   coerce(Integer) # => proc that calls Kernel.Integer
       #
+      # @example Array types
+      #   coerce([String]) # => proc that coerces array elements to String
+      #
       # @example Parseable types
       #   coerce(Date) # => proc that calls Date.parse
       #
-      # @example Array types
-      #   coerce([String]) # => proc that coerces array elements to String
+      # @example No coercion
+      #   coerce(nil) # => nil
+      #
+      # @example Custom lambdas
+      #   coerce(->(val) { val.upcase }) # => returns the lambda itself
       #
-      # @example String class name (lazy resolved)
+      # @example Lazy-resolved classes
       #   coerce("MyClass") # => proc that resolves and coerces to MyClass
-      def coerce(type, context_class = nil)
+      def coerce(type, context = nil)
         case type
         when :boolean
           boolean
         when :self
-          self_referential
-        when String
-          string_class(type, context_class)
+          self_referential(context)
+        when ->(t) { t.respond_to?(:name) && t.name && Kernel.respond_to?(t.name) }
+          kernel(type)
         when ->(t) { t.is_a?(Array) && t.length == 1 }
-          array(type.first, context_class)
-        when Hash
-          raise ArgumentError, "Cannot specify #{type.inspect} as type"
+          array(type.first, context)
         when ->(t) { t.respond_to?(:parse) }
           parseable(type)
-        when ->(t) { t.respond_to?(:name) && t.name && Kernel.respond_to?(t.name) }
-          kernel(type)
-        when ->(t) { t.respond_to?(:call) }
-          type
         when nil
           type
+        when ->(t) { t.respond_to?(:call) }
+          type
+        when String
+          lazy_class(type, context)
         else
           raise ArgumentError, "Cannot specify #{type.inspect} as type"
         end
       end
 
-      def resolve_class(class_name, context_class)
-        if context_class && defined?(context_class.name)
-          namespace = context_class.name.to_s.split("::")[0...-1]
-          if namespace.any?
-            begin
-              namespace.reduce(Object) { |mod, name| mod.const_get(name) }.const_get(class_name)
-            rescue NameError
-              Object.const_get(class_name)
-            end
-          else
-            Object.const_get(class_name)
-          end
-        else
-          Object.const_get(class_name)
-        end
-      rescue NameError => e
-        raise NameError, "Unable to resolve class '#{class_name}': #{e.message}"
-      end
-
       private
 
       def boolean
-        ->(val) { BOOLEAN_TRUTHY.include?(val) }
-      end
-
-      def self_referential
-        proc { |val| parse(val) }
+        @boolean ||= ->(val) { BOOLEAN_TRUTHY.include?(val) }
       end
 
-      def kernel(type)
-        ->(val) { Kernel.send(type.name, val) }
+      def self_referential(context)
+        ->(val) { context.parse(val) }
       end
 
-      def parseable(type)
-        ->(val) { type.parse(val) }
-      end
-
-      def string_class(class_name, context_class)
+      def lazy_class(class_name, context)
         resolved_class = nil
-        mutex = Mutex.new
 
-        proc do |value|
-          unless resolved_class
-            mutex.synchronize do
-              resolved_class ||= Structure::Types.resolve_class(class_name, context_class)
-            end
-          end
-
-          if resolved_class.respond_to?(:parse)
-            resolved_class.parse(value) # steep:ignore
-          else
-            value
-          end
+        ->(value) do
+          resolved_class ||= resolve_class(class_name, context)
+          # @type var resolved_class: untyped
+          resolved_class.parse(value)
         end
       end
 
-      def array(element_type, context_class = nil)
-        if element_type == :self
-          proc do |value|
+      def array(element_type, context = nil)
+        case element_type
+        when :self
+          lambda do |value|
             unless value.respond_to?(:map)
               raise TypeError, "can't convert #{value.class} into Array"
             end
 
-            value.map { |element| parse(element) }
+            value.map { |element| context.parse(element) }
           end
-        elsif element_type.is_a?(String)
-          proc do |value|
+        when String
+          lambda do |value|
             unless value.respond_to?(:map)
               raise TypeError, "can't convert #{value.class} into Array"
             end
 
-            resolved_class = Structure::Types.resolve_class(element_type, context_class)
-            value.map do |element|
-              if resolved_class.respond_to?(:parse)
-                resolved_class.parse(element)
-              else
-                element
-              end
-            end
+            resolved_class = resolve_class(element_type, context)
+            value.map { |element| resolved_class.parse(element) }
           end
         else
-          element_coercer = coerce(element_type, context_class)
+          element_coercer = coerce(element_type, context)
           lambda do |value|
             unless value.respond_to?(:map)
               raise TypeError, "can't convert #{value.class} into Array"
@@ -144,6 +112,35 @@ module Structure
           end
         end
       end
+
+      def parseable(type)
+        @parseable_cache ||= {} # : Hash[untyped, Proc]
+        @parseable_cache[type] ||= ->(val) { type.parse(val) }
+      end
+
+      def kernel(type)
+        @kernel_cache ||= {} # : Hash[untyped, Proc]
+        @kernel_cache[type] ||= ->(val) { Kernel.send(type.name, val) }
+      end
+
+      def resolve_class(class_name, context)
+        if context && defined?(context.name)
+          namespace = context.name.to_s.split("::")[0...-1]
+          if namespace.any?
+            begin
+              namespace.reduce(Object) { |mod, name| mod.const_get(name) }.const_get(class_name)
+            rescue NameError
+              Object.const_get(class_name)
+            end
+          else
+            Object.const_get(class_name)
+          end
+        else
+          Object.const_get(class_name)
+        end
+      rescue NameError => e
+        raise NameError, "Unable to resolve class '#{class_name}': #{e.message}"
+      end
     end
   end
 end

data/lib/structure/version.rb

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

data/lib/structure.rb

@@ -26,94 +26,95 @@ module Structure
       # @type var klass: untyped
       klass = Data.define(*builder.attributes)
 
-      # capture all metadata and attach to class - no closure capture needed
-      mappings = builder.mappings
-      coercions = builder.coercions(klass)
-      predicates = builder.predicate_methods
-      after = builder.after_parse_callback
+      # Override initialize to make optional attributes truly optional
+      optional_attrs = builder.optional
+      unless optional_attrs.empty?
+        klass.class_eval do
+          alias_method(:__data_initialize__, :initialize)
+
+          define_method(:initialize) do |**kwargs| # steep:ignore
+            optional_attrs.each do |attr|
+              kwargs[attr] = nil unless kwargs.key?(attr)
+            end
+            __data_initialize__(**kwargs) # steep:ignore
+          end
+        end
+      end
 
+      builder.predicate_methods.each do |pred, attr|
+        klass.define_method(pred) { !!public_send(attr) }
+      end
+
+      # Store metadata on class to avoid closure capture (memory optimization)
       meta = {
-        attributes: builder.attributes.freeze,
-        types: builder.types.freeze,
-        defaults: builder.defaults.freeze,
-        mappings: mappings.freeze,
-        coercions: coercions.freeze,
-        predicates: predicates.freeze,
-        after: after,
+        types: builder.types,
+        defaults: builder.defaults,
+        mappings: builder.mappings,
+        coercions: builder.coercions(klass),
+        after_parse: builder.after_parse_callback,
+        required: builder.required,
       }.freeze
       klass.instance_variable_set(:@__structure_meta__, meta)
       klass.singleton_class.attr_reader(:__structure_meta__)
 
-      # Define predicate methods
-      predicates.each do |pred, attr|
-        klass.define_method(pred) { !!public_send(attr) }
-      end
-
       # recursive to_h
       klass.define_method(:to_h) do
-        # @type var h: Hash[Symbol, untyped]
-        h = {}
-        klass.members.each do |m|
+        klass.members.to_h do |m|
           v = public_send(m)
-          h[m] =
-            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
-            else v
-            end
+          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
+          else v
+          end
+          [m, value]
         end
-        h
       end
 
-      # parse accepts JSON-ish hashes + kwargs override
-      klass.singleton_class.define_method(:parse) do |data = {}, **kwargs|
+      # parse accepts JSON-ish hashes + optional overrides hash
+      # overrides is a positional arg (not **kwargs) to avoid hash allocation when unused
+      #
+      # @type self: singleton(Data) & _StructuredDataClass
+      # @type var final: Hash[Symbol, untyped]
+      klass.singleton_class.define_method(:parse) do |data = {}, overrides = nil|
         return data if data.is_a?(self)
 
         unless data.respond_to?(:merge!)
           raise TypeError, "can't convert #{data.class} into #{self}"
         end
 
-        # @type var kwargs: Hash[Symbol, untyped]
-        string_kwargs = kwargs.transform_keys(&:to_s)
-        data.merge!(string_kwargs)
-        # @type self: singleton(Data) & _StructuredDataClass
-        # @type var final: Hash[Symbol, untyped]
-        final = {}
-
-        # @type var meta: untyped
-        meta = __structure_meta__
-
-        attributes = meta.fetch(:attributes)
-        defaults = meta.fetch(:defaults)
-        mappings = meta.fetch(:mappings)
-        coercions = meta.fetch(:coercions)
-        after = meta.fetch(:after)
-
-        attributes.each do |attr|
-          source = mappings[attr] || attr.to_s
-          value =
-            if data.key?(source)            then data[source]
-            elsif data.key?(source.to_sym)  then data[source.to_sym]
-            elsif defaults.key?(attr) then defaults[attr]
+        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]
+
+        # Check for missing required attributes
+        required.each do |attr|
+          from = mappings[attr]
+          next if data.key?(from) || data.key?(from.to_sym) || defaults.key?(attr)
+
+          raise ArgumentError, "missing keyword: :#{attr}"
+        end
+
+        mappings.each do |attr, from|
+          value = data.fetch(from) do
+            data.fetch(from.to_sym) do
+              defaults[attr]
             end
+          end
 
-          coercion = coercions[attr]
-          if coercion && !value.nil?
-            # Procs (not lambdas) need class context for self-referential parsing
-            # Lambdas and other callables use direct invocation
-            value =
-              if coercion.is_a?(Proc) && !coercion.lambda?
-                instance_exec(value, &coercion) # steep:ignore
-              else
-                coercion.call(value)
-              end
+          if value
+            coercion = __structure_meta__[:coercions][attr]
+            value = coercion.call(value) if coercion
           end
 
           final[attr] = value
         end
 
         obj = new(**final)
-        after&.call(obj)
+        after_parse&.call(obj)
         obj
       end
 

data/sig/structure/builder.rbs

@@ -4,18 +4,24 @@ module Structure
     @types: Hash[Symbol, untyped]
     @defaults: Hash[Symbol, untyped]
     @after_parse_callback: Proc?
+    @optional: 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?, ?default: untyped) ?{ (untyped) -> untyped } -> void
+                  | (Symbol name, ?from: String, ?default: untyped) ?{ (untyped) -> untyped } -> void
+
     def after_parse: () { (Data) -> void } -> void
 
     def attributes: () -> Array[Symbol]
     def mappings: () -> Hash[Symbol, String]
     def types: () -> Hash[Symbol, untyped]
     def defaults: () -> Hash[Symbol, untyped]
-    def coercions: (?untyped? context_class) -> Hash[Symbol, Proc]
+    def coercions: (?untyped? context) -> Hash[Symbol, Proc]
     def predicate_methods: () -> Hash[Symbol, Symbol]
+    def optional: () -> Array[Symbol]
+    def required: () -> Array[Symbol]
     def after_parse_callback: () -> (Proc | nil)
   end
 end

data/sig/structure/rbs.rbs

@@ -3,7 +3,7 @@ module Structure
     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], 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) -> 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
   end

data/sig/structure/types.rbs

@@ -1,18 +1,25 @@
 module Structure
   module Types
+    interface _ParseableClass
+      def parse: (untyped) -> untyped
+    end
+
     BOOLEAN_TRUTHY: Array[untyped]
 
     self.@boolean: Proc
+    self.@kernel_cache: Hash[untyped, Proc]
+    self.@parseable_cache: Hash[untyped, Proc]
+    self.@string_class_cache: Hash[Array[untyped], Proc]
 
-    def self.coerce: (untyped type, ?untyped? context_class) -> untyped
-    def self.resolve_class: (String class_name, untyped? context_class) -> untyped
+    def self.coerce: (untyped type, ?untyped? context) -> untyped
 
     private def self.boolean: () -> Proc
-    private def self.self_referential: () -> Proc
-    private def self.string_class: (String class_name, untyped? context_class) -> Proc
-    private def self.array: (untyped element_type, ?untyped? context_class) -> Proc
+    private def self.self_referential: (_ParseableClass context) -> Proc
+    private def self.lazy_class: (String class_name, untyped? context) -> Proc
+    private def self.array: (untyped element_type, ?untyped? context) -> Proc
     private def self.parseable: (untyped type) -> Proc
     private def self.kernel: (Class type) -> Proc
     private def self.parse: (untyped val) -> untyped
+    private def self.resolve_class: (String class_name, untyped? context) -> _ParseableClass
   end
 end

data/sig/structure.rbs

@@ -1,13 +1,12 @@
 module Structure
   interface _StructuredDataClass
     def __structure_meta__: () -> {
-      attributes: Array[Symbol],
       types: Hash[Symbol, untyped],
       defaults: Hash[Symbol, untyped],
       mappings: Hash[Symbol, String],
       coercions: Hash[Symbol, untyped],
-      predicates: Hash[Symbol, Symbol],
-      after: untyped
+      after_parse: untyped,
+      required: Array[Symbol]
     }
   end
 

metadata

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