structure 3.6.3 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ecf2906322a2c0abaa86ab756c7154139788867b214ee5b30a071adf5e044ff
-  data.tar.gz: c36c7b4dfc5656a74b056c72af11ab478fc97886a1638312dd389d252e1977b3
+  metadata.gz: 272646d259a42b8a13d4c0fbc29072022da5260f5a7948d2f8dbaddb9f625adf
+  data.tar.gz: a3045255ecb35adc801f827c48a5c620dc90943aee453f474bae6ab85bc8b58d
 SHA512:
-  metadata.gz: f6bcd31e925af5a25bb65b9ee1b2c4eff4654b7fbce6e7110d3c89195744b5ed7f3564a33dcf0b0cf19a373df315d955637388ccad8f6fa19aa394b21234e1d5
-  data.tar.gz: 3707eb84b1b0e702f4e13cf90b9048a3858ed71b07e399d969db4e4e36523fa4e9860c38fbe0d33a4b11336fb2b9f7389d136e80fa4ed280cd0301297102de56
+  metadata.gz: 4d5914cb2446f277c61369d156d8286cfc50b866423b7bc86523964216d76a677901848a3135a5f1061f0383569fb3ad03624c3806de9d7841281bd751e5aa16
+  data.tar.gz: 3684e0a22399da848c493eb6b837d0c8427f0dd6f24857a7f65812914366b448108da8af2b377fc937a08715ea13de633b3f538f6b843a288c65936123dd32b7

data/lib/structure/builder.rb

@@ -5,12 +5,14 @@ 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 = {}
     end
 
     # DSL method for defining attributes with optional type coercion
@@ -56,14 +58,17 @@ module Structure
       @after_parse_callback = block
     end
 
+    # @api private
     def attributes
       @mappings.keys
     end
 
-    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,13 @@ 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
+
         emit_rbs_content(
-          class_name: class_name,
-          attributes: meta.fetch(:attributes, klass.members),
-          types: meta.fetch(:types, {}), # steep:ignore
+          class_name:,
+          attributes:,
+          types:,
           has_structure_modules: meta.any?,
         )
       end

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 = "3.7.0"
 end

data/lib/structure.rb

@@ -26,94 +26,70 @@ 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
+      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,
       }.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 = {}
+        overrides&.each { |k, v| data[k.to_s] = v }
 
-        # @type var meta: untyped
-        meta = __structure_meta__
+        final       = {}
+        mappings    = __structure_meta__[:mappings]
+        defaults    = __structure_meta__[:defaults]
+        after_parse = __structure_meta__[:after_parse]
 
-        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]
+        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

@@ -14,7 +14,7 @@ module Structure
     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 after_parse_callback: () -> (Proc | nil)
   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,11 @@
 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
     }
   end
 

metadata

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