structure 4.4.0 → 4.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70c0f08018c0b2adccf83a0fd310719e21e79e2f0945d753fef9df5a08226537
-  data.tar.gz: e62bbdc33e63db5845d816ba84bbde60433e4137d95a7466dbbcd1376891eccf
+  metadata.gz: 548fe77f526e4c9f238da59611f13c3f13614f3111f3cf466054bacb84883b18
+  data.tar.gz: f6bda78f70879a1d373c8b5aa1aeb0ef3475004b0475ac5100adf9b6bfa5e657
 SHA512:
-  metadata.gz: 4acad52488ad58e454cf052b14727aa70f75bfb921ee5ffb92310287194b2be4019caa98c5afd995df64a9a6356eafde4f6ffcb33680dc504355a79c575ba801
-  data.tar.gz: 9ed2e262bdf3488c5b074b9b1e8148049908883a92deaec90cd969715ff34879231017bbe7061b0a6d3ac9c812dc999497884f383754987e7bee9a64661e0027
+  metadata.gz: 84f01c87a3e85b73d364d3994b1c0af646aedd50db182e9966b48bb21cc77432448342986931600f843b62c58677202247888791f58c901e809d1830e944915e
+  data.tar.gz: 8d65b5847a2c6839f49cd66ad9a0d08afa7eda6adeba4930dcb79fcff97b8f580e639b0b9a1c13c1a64c4f31c16a72a9517201998793d2c16143e44af69a7d95

data/lib/structure/builder.rb

@@ -41,14 +41,15 @@ module Structure
     # @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
+      key = from || name
+      mappings[name] = key.is_a?(Symbol) ? key.name : -key.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}"
       else
-        types[name] = type || block
+        types[name] = shareable(type) || shareable_block(block)
       end
     end
 
@@ -77,15 +78,22 @@ module Structure
 
     # Defines a callback to run after parsing
     #
+    # @param callable [#call, nil] Object that receives the parsed instance, such as a module with a call method
     # @yield [instance] Block that receives the parsed instance
     # @return [void]
+    # @raise [ArgumentError] If both a callable and a block are provided
     #
     # @example Validation
     #   after_parse do |order|
     #     raise "Invalid order" if order.total < 0
     #   end
-    def after_parse(&block)
-      @after_parse_callback = block
+    #
+    # @example With a module, which any Ractor can call
+    #   after_parse(OrderValidator)
+    def after_parse(callable = nil, &block)
+      raise ArgumentError, "cannot specify both a callable and a block for after_parse" if callable && block
+
+      @after_parse_callback = callable || shareable_block(block)
     end
 
     # @api private
@@ -104,7 +112,7 @@ module Structure
     def coercions(context = nil)
       @types.to_h do |attr, type|
         coercion = Types.coerce(type, context)
-        [attr, coercion]
+        [attr, coercion] #: [Symbol, Proc]
       rescue ArgumentError => e
         raise ArgumentError, "#{e.message} for :#{attr}"
       end
@@ -118,5 +126,32 @@ module Structure
         end
       end.to_h
     end
+
+    private
+
+    # Before Ruby 4.1, Ractors that call the same shareable block share its $~
+    # (https://bugs.ruby-lang.org/issues/22216), so one that matches a Regexp would read another Ractor's match. A block
+    # is shared from 4.1 only, and only when Ruby can: one that uses a local variable from around it stays as it is.
+    if defined?(Ractor) && Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("4.1")
+      def shareable_block(block)
+        block && Ractor.shareable_proc(&block) # steep:ignore
+      rescue Ractor::IsolationError, ArgumentError
+        block
+      end
+    else
+      def shareable_block(block)
+        block
+      end
+    end
+
+    # Returns the type as another Ractor can read it: a frozen copy of an Array or of a class name. The caller's own
+    # object is left as it is.
+    def shareable(type)
+      case type
+      when Array then type.map { |element| shareable(element) }.freeze
+      when String then -type
+      else type
+      end
+    end
   end
 end

data/lib/structure/types.rb

@@ -64,28 +64,39 @@ module Structure
         end
       end
 
+      # Makes an object shareable when Ruby can. A lambda that closes over a caller's unshareable object can't be,
+      # and comes back as it is. Where Ruby has no Ractor, nothing is shared.
+      if defined?(Ractor)
+        # @api private
+        def shareable(object)
+          Ractor.make_shareable(object)
+        rescue Ractor::IsolationError
+          object
+        end
+      else
+        # @api private
+        def shareable(object)
+          object
+        end
+      end
+
       private
 
       def boolean
-        @boolean ||= ->(val) { BOOLEAN_TRUTHY.include?(val) }
+        @boolean ||= shareable(->(val) { BOOLEAN_TRUTHY.include?(val) })
       end
 
       def self_referential(context)
-        ->(val) { context.parse(val) }
+        shareable(->(val) { context.parse(val) })
       end
 
       def lazy_class(class_name, context)
-        resolved_class = nil
-
-        ->(value) do
-          resolved_class ||= resolve_class(class_name, context)
-          # @type var resolved_class: untyped
-          resolved_class.parse(value)
-        end
+        key = shareable(Object.new)
+        shareable(->(value) { parse_as(resolved_class(key, class_name, context), value) })
       end
 
       def array(element_type, context = nil)
-        case element_type
+        coercion = case element_type
         when :self
           lambda do |value|
             unless value.respond_to?(:map)
@@ -95,16 +106,14 @@ module Structure
             value.map { |element| context.parse(element) }
           end
         when String
-          resolved_class = nil
-
+          key = shareable(Object.new)
           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)
-            # @type var resolved_class: untyped
-            value.map { |element| resolved_class.parse(element) }
+            element_class = resolved_class(key, element_type, context)
+            value.map { |element| parse_as(element_class, element) }
           end
         else
           element_coercer = coerce(element_type, context)
@@ -116,16 +125,38 @@ module Structure
             value.map { |element| element_coercer.call(element) }
           end
         end
+
+        shareable(coercion)
       end
 
       def parseable(type)
         @parseable_cache ||= {} # : Hash[untyped, Proc]
-        @parseable_cache[type] ||= ->(val) { type.parse(val) }
+        @parseable_cache[type] ||= shareable(->(val) { parse_as(type, val) })
+      end
+
+      # A method must make this call, not a lambda. A parser written in C, such as Date.parse, keeps its match in
+      # the caller's $~, and a lambda shared between Ractors shares its $~ too.
+      def parse_as(type, val)
+        type.parse(val)
       end
 
       def kernel(type)
         @kernel_cache ||= {} # : Hash[untyped, Proc]
-        @kernel_cache[type] ||= ->(val) { Kernel.send(type.name, val) }
+        @kernel_cache[type] ||= shareable(->(val) { Kernel.send(type.name, val) })
+      end
+
+      # Resolves a class given by name once in each Ractor. A shareable lambda can't keep the class itself, so it
+      # keeps a key into a weak map in the Ractor's local storage. Where Ruby has no Ractor, the key keeps the class.
+      if defined?(Ractor)
+        def resolved_class(key, class_name, context)
+          classes = Ractor.current[:__structure_classes__] ||= ObjectSpace::WeakMap.new # steep:ignore
+          classes[key] ||= resolve_class(class_name, context)
+        end
+      else
+        def resolved_class(key, class_name, context)
+          key.instance_variable_get(:@resolved) ||
+            key.instance_variable_set(:@resolved, resolve_class(class_name, context))
+        end
       end
 
       def resolve_class(class_name, context)

data/lib/structure/version.rb

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

data/lib/structure.rb

@@ -4,7 +4,7 @@ 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 }
+  TO_H_CHECKER = Types.shareable(->(x) { x.respond_to?(:to_h) && x })
   private_constant :TO_H_CHECKER
 
   class << self
@@ -29,7 +29,7 @@ module Structure
       # @type var klass: untyped
       klass = Data.define(*builder.attributes)
 
-      custom_methods_metadata = { instance: [], singleton: [] }.freeze # steep:ignore
+      custom_methods_metadata = { instance: [].freeze, singleton: [].freeze }.freeze # steep:ignore
 
       # Enable custom method definitions by evaluating block on the class
       if block
@@ -39,7 +39,7 @@ module Structure
         # 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| }
-        klass.define_singleton_method(:after_parse) { |&blk| }
+        klass.define_singleton_method(:after_parse) { |*args, &blk| }
 
         # Evaluate block in class context for method definitions
         klass.class_eval(&block)
@@ -60,7 +60,7 @@ module Structure
 
           {
             name: name,
-            parameters: klass.instance_method(name).parameters,
+            parameters: Types.shareable(klass.instance_method(name).parameters),
           }.freeze
         end
 
@@ -70,7 +70,7 @@ module Structure
 
           {
             name: name,
-            parameters: singleton_class.instance_method(name).parameters,
+            parameters: Types.shareable(singleton_class.instance_method(name).parameters),
           }.freeze
         end
 
@@ -81,42 +81,46 @@ module Structure
       end
 
       # Override initialize to make optional attributes truly optional
-      optional_attrs = builder.optional
+      optional_attrs = builder.optional.freeze
       unless optional_attrs.empty?
-        klass.class_eval do
-          alias_method(:__data_initialize__, :initialize)
+        klass.alias_method(:__data_initialize__, :initialize)
 
-          # 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:start
+        define_shareable_method(klass, :initialize) do |**kwargs|
+          optional_attrs.each do |attr|
+            kwargs[attr] = nil unless kwargs.key?(attr)
           end
-          # steep:ignore:end
+          __data_initialize__(**kwargs)
         end
+        # steep:ignore:end
       end
 
       builder.predicate_methods.each do |pred, attr|
-        klass.define_method(pred) { !!public_send(attr) }
+        define_common_method(klass, pred) { !!public_send(attr) }
       end
 
-      # Store metadata on class to avoid closure capture (memory optimization)
-      meta = {
-        types: builder.types,
-        defaults: builder.defaults,
-        mappings: builder.mappings,
-        coercions: builder.coercions(klass),
+      # Store metadata on class to avoid closure capture (memory optimization). What Structure builds of it is
+      # frozen, so the whole is shareable when the caller's own types, defaults and blocks are, and then any
+      # Ractor can parse.
+      klass.instance_variable_set(:@__structure_meta__, {
+        types: builder.types.freeze,
+        defaults: builder.defaults.freeze,
+        mappings: builder.mappings.freeze,
+        coercions: builder.coercions(klass).freeze,
         after_parse: builder.after_parse_callback,
-        required: builder.required,
-        non_nullable: builder.non_nullable,
+        required: builder.required.freeze,
+        non_nullable: builder.non_nullable.freeze,
         custom_methods: custom_methods_metadata,
-      }.freeze
-      klass.instance_variable_set(:@__structure_meta__, meta)
-      klass.singleton_class.attr_reader(:__structure_meta__)
+      }.freeze)
+      define_common_method(klass.singleton_class, :__structure_meta__) do
+        @__structure_meta__
+      rescue Ractor::IsolationError
+        raise Ractor::IsolationError,
+          "#{self} parses only in the main Ractor: a type, block, default or after_parse callback is not shareable"
+      end
 
       # recursive to_h
-      klass.define_method(:to_h) do
+      define_shareable_method(klass, :to_h) do
         klass.members.to_h do |m|
           v = public_send(m)
           value = case v
@@ -130,10 +134,9 @@ module Structure
 
       # 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|
+      define_common_method(klass.singleton_class, :parse) do |data = {}, overrides = nil|
+        # @type self: singleton(Data) & _StructuredDataClass
+        # @type var final: Hash[Symbol, untyped]
         return data if data.is_a?(self)
 
         unless data.respond_to?(:merge!)
@@ -143,12 +146,13 @@ module Structure
         overrides&.each { |k, v| data[k.to_s] = v }
 
         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]
+        meta         = __structure_meta__
+        mappings     = meta[:mappings]
+        defaults     = meta[:defaults]
+        coercions    = meta[:coercions]
+        after_parse  = meta[:after_parse]
+        required     = meta[:required]
+        non_nullable = meta[:non_nullable]
 
         # Check for missing required attributes
         required.each do |attr|
@@ -186,10 +190,25 @@ module Structure
         obj
       end
 
-      klass.define_singleton_method(:load) { |data| parse(data) if data } # steep:ignore
-      klass.define_singleton_method(:dump) { |value| value&.to_h }
+      define_common_method(klass.singleton_class, :load) { |data| parse(data) if data } # steep:ignore
+      define_common_method(klass.singleton_class, :dump) { |value| value&.to_h }
 
       klass
     end
+
+    private
+
+    # Defines a method that any Ractor can call, not only the one that defined it. The block may read only locals
+    # that hold shareable values and are assigned once.
+    def define_shareable_method(target, name, &block)
+      target.define_method(name, &Types.shareable(block))
+    end
+
+    # The same, for a method whose block is identical for every structure. The first block given for a name is
+    # made shareable once and reused; later ones are ignored.
+    def define_common_method(target, name, &block)
+      @common_methods ||= {} # : Hash[Symbol, Proc]
+      target.define_method(name, &(@common_methods[name] ||= Types.shareable(block)))
+    end
   end
 end

data/sig/structure/builder.rbs

@@ -3,7 +3,7 @@ module Structure
     @mappings: Hash[Symbol, String]
     @types: Hash[Symbol, untyped]
     @defaults: Hash[Symbol, untyped]
-    @after_parse_callback: Proc?
+    @after_parse_callback: untyped
     @optional: Set[Symbol]
     @non_nullable: Set[Symbol]
 
@@ -13,7 +13,7 @@ module Structure
     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
+    def after_parse: (?untyped callable) ?{ (Data) -> void } -> void
 
     def attributes: () -> Array[Symbol]
     def mappings: () -> Hash[Symbol, String]
@@ -24,7 +24,10 @@ module Structure
     def optional: () -> Array[Symbol]
     def required: () -> Array[Symbol]
     def non_nullable: () -> Array[Symbol]
-    def after_parse_callback: () -> (Proc | nil)
+    def after_parse_callback: () -> untyped
+
+    private def shareable: (untyped type) -> untyped
+    private def shareable_block: (Proc? block) -> Proc?
 
     def method_missing: (Symbol, *untyped, **untyped) ?{ (*untyped, **untyped) -> untyped } -> untyped
     def respond_to_missing?: (Symbol, bool) -> bool

data/sig/structure/types.rbs

@@ -12,14 +12,17 @@ module Structure
     self.@string_class_cache: Hash[Array[untyped], Proc]
 
     def self.coerce: (untyped type, ?untyped? context) -> untyped
+    def self.shareable: [T] (T object) -> T
 
     private def self.boolean: () -> 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.parse_as: (untyped type, untyped val) -> untyped
     private def self.kernel: (Class type) -> Proc
     private def self.parse: (untyped val) -> untyped
+    private def self.resolved_class: (Object key, String class_name, untyped? context) -> _ParseableClass
     private def self.resolve_class: (String class_name, untyped? context) -> _ParseableClass
   end
 end

data/sig/structure.rbs

@@ -1,6 +1,8 @@
 module Structure
   TO_H_CHECKER: Proc
 
+  self.@common_methods: Hash[Symbol, Proc]
+
   interface _StructuredDataClass
     def __structure_meta__: () -> {
       types: Hash[Symbol, untyped],
@@ -15,4 +17,7 @@ module Structure
   # 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
+
+  private def self.define_shareable_method: (untyped target, Symbol name) { (?) -> untyped } -> void
+  private def self.define_common_method: (untyped target, Symbol name) { (?) -> untyped } -> void
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: structure
 version: !ruby/object:Gem::Version
-  version: 4.4.0
+  version: 4.5.0
 platform: ruby
 authors:
 - Hakan Ensari
@@ -37,14 +37,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Structure your data
 test_files: []