safe_ostruct 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b350ef819ecad8545a838c5e3a1c1840fbbe7f64c8455a56a0afa304e4e1d7e
-  data.tar.gz: ff69a99e6fba10bf86c54cc360e4ae41c31add767ccd3e080eaa325a754c88b5
+  metadata.gz: 9b0df898c8251bc9194d8c10a6b1a757ca50fc4933e864a8a4fc1120ea59a957
+  data.tar.gz: 5373099a228a7bd3ac7b4ec60946a5c4fdd30bb5a8baf4923aeb8aaca73335c6
 SHA512:
-  metadata.gz: 68b2240672f66147033bc97efcc01b0a06747cf8b89d327236ac445fd1b72005cf40ed759a1127922134e70cb5934771fb4663d9fd4292d6910b5dae8c53a955
-  data.tar.gz: 959d453d08c5ee503883c6279f9c747dff73fe73368c3ef1c9a720356c5532b9064b17f0005b2aaf36b656fa505bbcc73d766fbbca6497b34e8cc812c9772815
+  metadata.gz: 67d7be1d36a08b01eb72ba30d1cd02a571d4781744a37356d500a8248bf4144a3a86c29ef643be07b0f31f9f8b6ce0b4d7806ebdf832c3eb75a80c19050d2406
+  data.tar.gz: 3d8f958423503e3999db6ccb5e361be2d91b38a474cd3e24a7b22e1e2e6c2f143aa28d9eb0413253ed93b2a4bce3004460e4aea63c4b51b875990ed8ae2a2646

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [2.0.0] - 2026-07-27
+
+Performance rework: attribute access now runs at Struct speed (within ~10% of raw Hash access, up from ~6x slower in 1.x).
+
+- `SafeOstruct.new` returns instances of cached per-key-set shape classes with real `attr_accessor` methods; `method_missing` remains only as a fallback for dynamically added and undefined attributes.
+- Added OpenStruct API parity: `==`, `eql?`, `hash`, `dig`, `each_pair`, `inspect`, `to_s`.
+- Breaking: `to_h` returns a fresh hash instead of the live internal hash.
+- Breaking: `respond_to?` is now true for shape attributes and their setters, even after `delete_field`.
+- Breaking: `.class` of an instance is an anonymous shape subclass; use `is_a?(SafeOstruct)` for type checks.
+- Breaking: `Marshal.dump` is not supported (anonymous classes); serialize via `to_h`.
+- The shape cache is capped at 1000 classes per base class; beyond that, instances degrade gracefully to `method_missing`-based access.
+
 ## [1.0.0] - 2026-07-27
 
 - Initial release.

data/README.md

@@ -1,8 +1,8 @@
 # SafeOstruct
 
-A lightweight, dependency-free `OpenStruct` alternative backed by a plain symbol-keyed `Hash`. Published as the `safe_ostruct` gem.
+A fast, dependency-free `OpenStruct` alternative. Published as the `safe_ostruct` gem.
 
-SafeOstruct gives you the ergonomics of `OpenStruct` (dynamic attributes, method-style access) without its cost: it never defines singleton methods, so instantiation stays fast and Ruby's method caches stay intact. Undefined attributes return `nil` instead of raising `NoMethodError`, which makes it a natural fit for API response objects, test doubles, and data with optional fields.
+SafeOstruct gives you the ergonomics of `OpenStruct` (dynamic attributes, method-style access) at near-Hash speed. Attribute reads and writes are real methods on cached per-key-set "shape" classes, not `method_missing` dispatch, so they run at Struct speed (within ~10% of raw Hash access). Undefined attributes return `nil` instead of raising `NoMethodError`, which makes it a natural fit for API response objects, test doubles, and data with optional fields.
 
 ## Installation
 
@@ -21,7 +21,7 @@ gem install safe_ostruct
 ## Usage
 
 ```ruby
-require "safe_ostruct" # `require "safe_ostruct"` works too
+require "safe_ostruct"
 
 obj = SafeOstruct.new(name: "John Doe")
 
@@ -42,8 +42,14 @@ obj[:age]     # => nil
 obj.delete_field(:address)
 obj.address   # => nil
 
-# Convert to a hash
+# Convert to a hash (a fresh copy, safe to mutate)
 obj.to_h      # => { name: "John Doe", city: "Springfield" }
+
+# OpenStruct API parity
+obj == SafeOstruct.new(name: "John Doe", city: "Springfield")  # => true
+obj.dig(:name)                                                 # => "John Doe"
+obj.each_pair { |key, value| ... }
+obj.inspect   # => #<SafeOstruct name="John Doe", city="Springfield">
 ```
 
 It also works as a `JSON.parse` object class for dot-notation access to parsed JSON:
@@ -65,32 +71,43 @@ class ResponseResult < SafeOstruct
 end
 ```
 
+## How it works
+
+`SafeOstruct.new` returns an instance of a cached subclass generated per unique key set (a "shape"). The shape class carries real `attr_accessor` methods backed by instance variables, so `obj.name` is an ordinary inline-cached method call instead of `method_missing` dispatch. Creating many structs with the same keys reuses one class, so the method cache stays intact (the classic OpenStruct problem). The shape cache is capped at `SafeOstruct::SHAPE_CACHE_LIMIT` (1000) classes per base class; beyond that, instances degrade gracefully to `method_missing`-based access, so arbitrary key sets (e.g. from JSON) cannot create classes unboundedly.
+
+`method_missing` remains as a fallback for attributes added after creation and for undefined attributes, which always return `nil`.
+
 ## Behavior notes
 
-These behaviors are intentional and covered by the test suite. They will not change without a major version bump.
+These behaviors are intentional and covered by the test suite.
 
 - **Every undefined method returns `nil`.** `obj.anything` returns `nil` rather than raising `NoMethodError`. This includes typos, so prefer SafeOstruct where absent-means-nil is the semantics you want, and avoid it where a typo should fail loudly.
-- **`respond_to?` only reflects currently set attributes.** `obj.respond_to?(:missing)` is `false` even though `obj.missing` returns `nil`, and `respond_to?(:attr=)` is `false` even though assignment works. Duck-type checks via `respond_to?` will only see attributes that have been set.
-- **`to_h` returns the live internal hash, not a copy.** Mutating the returned hash mutates the struct. Call `obj.to_h.dup` if you need an independent copy.
+- **`to_h` returns a fresh hash.** Mutating the returned hash does not affect the struct.
+- **`respond_to?` is true for shape attributes** (getters and setters, even after `delete_field`), and true for dynamically added attributes while they hold a value. It stays false for attributes that were never set.
+- **`.class` is an anonymous shape subclass.** Use `is_a?(SafeOstruct)` (or your own base class) for type checks, not `.class ==`. Structs with equal attributes are `==` regardless of shape.
+- **Keys that are not valid method names** (e.g. `"foo-bar"`) or that collide with existing methods (e.g. `:to_h`, `:class`) are stored and fully accessible hash-style (`obj[:"foo-bar"]`), just not via dot access. Keys starting with `__` are reserved for internal storage.
+- **Marshal is not supported** because shape classes are anonymous. Serialize via `obj.to_h` instead.
+- **Subclass instance variables appear in `to_h`.** Attribute storage is instance variables, so a subclass that memoizes internal state into an ivar will see it in `to_h`; prefix internal ivars with `__` to exclude them.
 
 ## Performance
 
-SafeOstruct exists for a specific trade: it is dramatically cheaper than `OpenStruct` to create, at the cost of slower per-attribute access (every read and write goes through `method_missing`). For the common lifecycle of value objects (create once, read a handful of attributes), creation cost dominates and SafeOstruct wins comfortably. If you create an object once and read the same attribute millions of times, use `Struct` or `Data` instead.
-
-Results from `benchmark/ips.rb` (Ruby 3.2.2, x86_64-linux, higher is better):
+Attribute access runs at Struct speed because shape attributes are real `attr_accessor` methods. Results from `benchmark/ips.rb` (Ruby 3.2.2, x86_64-linux, YJIT disabled, higher is better):
 
 | Operation | Hash | Struct | SafeOstruct | OpenStruct |
 |---|---|---|---|---|
-| Instantiation (3 attributes) | 13.9M i/s | 10.5M i/s | 3.2M i/s | 0.16M i/s |
-| Defined attribute read | 61.1M i/s | 57.7M i/s | 9.2M i/s | 27.9M i/s |
-| Undefined attribute read | n/a | n/a | 9.2M i/s | 7.3M i/s |
-| Attribute write | 41.4M i/s | n/a | 4.8M i/s | 21.5M i/s |
+| Defined attribute read | 61.0M i/s | 58.3M i/s | 55.6M i/s | 28.1M i/s |
+| Attribute write | 42.1M i/s | n/a | 53.0M i/s | 20.0M i/s |
+| Instantiation (3 attributes) | 13.6M i/s | 10.1M i/s | 2.0M i/s | 0.16M i/s |
+| Undefined attribute read | n/a | n/a | 6.2M i/s | 7.2M i/s |
+| Dynamically added attribute read | n/a | n/a | 6.9M i/s | n/a |
+| Hash-style read (`[]`) | 56.7M i/s | n/a | 20.0M i/s | 28.9M i/s |
 
 Highlights:
 
-- **Instantiation is ~20x faster than OpenStruct.** OpenStruct defines singleton methods per instance, which is slow and invalidates method caches; SafeOstruct just stores a hash.
-- **Reads of defined attributes are ~3x slower than OpenStruct** (9.2M vs 27.9M i/s), because OpenStruct's lazily defined accessor is a real method while SafeOstruct always dispatches through `method_missing`.
-- Direct `Hash` or `Struct` access is roughly 6x faster than SafeOstruct. When attribute names are fixed and known up front, prefer those.
+- **Reads are within 10% of raw Hash access** and effectively at Struct speed. Writes are faster than `Hash#[]=`.
+- **Instantiation is ~12x faster than OpenStruct**, which defines singleton methods per instance. It is slower than a bare Struct because of the shape-cache lookup; the cost is repaid after about two attribute accesses per object.
+- Attributes added after creation (and undefined reads) go through the `method_missing` fallback at ~6-7M i/s, comparable to OpenStruct's lazily defined accessors.
+- YJIT narrows the remaining gaps further.
 
 Run the benchmark yourself:
 
@@ -98,6 +115,15 @@ Run the benchmark yourself:
 bundle exec ruby benchmark/ips.rb
 ```
 
+## Migrating from 1.x
+
+Version 2.0.0 changed the storage model from a single internal hash to shape classes. Interface-compatible, with these semantic differences:
+
+- `to_h` returns a fresh hash instead of the live internal hash; code that mutated the struct through `to_h` must use `[]=` instead.
+- `respond_to?` now reflects shape accessors (true for initial attributes and their setters, even after `delete_field`).
+- `.class` is an anonymous shape subclass rather than `SafeOstruct` itself; `is_a?(SafeOstruct)` still holds.
+- `Marshal.dump` no longer works; use `to_h`.
+
 ## Development
 
 ```bash

data/lib/safe_ostruct/version.rb

@@ -1,3 +1,3 @@
 class SafeOstruct
-  VERSION = "1.0.0".freeze
+  VERSION = "2.0.0".freeze
 end

data/lib/safe_ostruct.rb

@@ -2,13 +2,17 @@ require_relative "safe_ostruct/version"
 
 # SafeOstruct
 #
-# SafeOstruct is a flexible struct-like class that allows dynamic initialization of attributes
-# using keyword arguments. It handles missing methods gracefully by returning `nil`
-# instead of raising a `NoMethodError` for undefined attributes or methods.
-# This class use Symbolic-Hash and its underlying data structure.
+# SafeOstruct is a fast, flexible struct-like class with an OpenStruct-style
+# interface. It handles missing methods gracefully by returning `nil` instead
+# of raising a `NoMethodError` for undefined attributes or methods.
 #
-# Additionally, it supports dynamically adding and removing attributes. The object allows access
-# to its attributes using both methods and hash-style key access with symbols or strings.
+# For speed, `SafeOstruct.new` returns an instance of a cached "shape" subclass
+# generated per unique key set. Shape classes carry real `attr_accessor`
+# methods backed by instance variables, so attribute reads and writes are
+# ordinary inline-cached method calls (Struct-like speed) rather than
+# `method_missing` dispatch. `method_missing` remains as a fallback for
+# attributes added after creation and always returns `nil` for anything
+# undefined.
 #
 # Key features:
 # - Define attributes dynamically with keyword arguments.
@@ -16,87 +20,208 @@ require_relative "safe_ostruct/version"
 # - Support both symbol and string access for attributes.
 # - Dynamically add or update attributes using method assignment or hash-style assignment.
 # - Remove attributes dynamically using `delete_field`.
+# - OpenStruct API parity: `==`, `eql?`, `hash`, `dig`, `each_pair`, `inspect`.
 #
 # Example usage:
 #   obj = SafeOstruct.new(name: 'John Doe')
 #
-#   # Accessing defined attributes
 #   obj.name           # => 'John Doe'
 #   obj[:name]         # => 'John Doe'
 #   obj['name']        # => 'John Doe'
 #
-#   # Adding new attributes dynamically
 #   obj.address = '123 Main St'
-#   obj.address        # => '123 Main St'
-#   obj[:address]      # => '123 Main St'
-#   obj['address']     # => '123 Main St'
+#   obj.age            # => nil (undefined attributes return nil)
 #
-#   # Accessing an undefined attribute returns nil
-#   obj.age            # => nil
-#   obj[:age]          # => nil
-#   obj['age']         # => nil
-#
-#   # Deleting an attribute
 #   obj.delete_field(:address)
-#   obj.address        # => nil
-#   obj.respond_to?(:address) # => false
-#
-#   # Converting to a hash
-#   hash_representation = obj.to_h
-#   # hash_representation => { name: 'John Doe' }
+#   obj.to_h           # => { name: 'John Doe' }
 #
-# This class simplifies working with dynamic or optional attributes and allows for greater
-# flexibility in handling data structures, especially when attribute names may not be known
-# in advance or when optional fields are common.
+# Storage model: attribute values live in instance variables (`@name`), except
+# keys that are not valid identifiers (e.g. `"foo-bar"`) or that start with
+# `__`, which live in an internal overflow hash and are reachable via `[]`,
+# `to_h`, `each_pair`, and `delete_field`. Keys that collide with existing
+# methods (e.g. `:to_h`, `:class`) are stored but only reachable hash-style.
 #
 class SafeOstruct
-  # Initializes the SafeOstruct with attributes provided as keyword arguments or a hash.
+  # Attribute names that can be stored as instance variables.
+  VALID_ATTRIBUTE_NAME = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
+  # Maximum number of shape classes cached per base class. Beyond this,
+  # instances are built on the base class itself (correct but slower),
+  # so arbitrary key sets (e.g. from JSON) cannot create classes unboundedly.
+  SHAPE_CACHE_LIMIT = 1000
+
+  # Memoized attribute-key to ivar-name mapping shared by all instances.
+  # Keys that cannot be stored as ivars map to nil (they use overflow
+  # storage). Grows by one entry per distinct attribute name ever used;
+  # the default proc runs under the GVL, so a race only recomputes.
+  IVAR_LOOKUP = Hash.new do |cache, key|
+    valid = VALID_ATTRIBUTE_NAME.match?(key) && !key.start_with?("__")
+    cache[key] = valid ? :"@#{key}" : nil
+  end
+  private_constant :IVAR_LOOKUP
+
+  @__shape__ = false
+  @__shapes__ = {}
+  @__shapes_lock__ = Mutex.new
+  @__overflow_keys__ = [].freeze
+  @__base__ = nil
+
+  class << self
+    # @return [Array<Symbol>] frozen list of shape keys stored in the overflow hash
+    attr_reader :__overflow_keys__
+
+    # @return [Class, nil] the user-visible class a shape was generated from
+    attr_reader :__base__
+
+    def inherited(subclass)
+      super
+      subclass.instance_variable_set(:@__shape__, false)
+      subclass.instance_variable_set(:@__shapes__, {})
+      subclass.instance_variable_set(:@__shapes_lock__, Mutex.new)
+      subclass.instance_variable_set(:@__overflow_keys__, [].freeze)
+      subclass.instance_variable_set(:@__base__, nil)
+    end
+
+    # Builds an instance of the cached shape class for the given key set.
+    # On shape classes this constructs normally.
+    #
+    # @param kwargs [Hash] the attributes to initialize the struct with
+    # @return [SafeOstruct]
+    def new(**kwargs)
+      return super if @__shape__
+
+      keys = kwargs.keys
+      unless keys.all?(Symbol)
+        kwargs = kwargs.transform_keys(&:to_sym)
+        keys = kwargs.keys
+      end
+      shape = __shape_for__(keys)
+      if shape
+        instance = shape.allocate
+        instance.__send__(:__shape_init__, kwargs)
+      else
+        instance = allocate
+        instance.__send__(:__init_attributes__, kwargs)
+      end
+      instance
+    end
+
+    private
+
+    def __shape_for__(keys)
+      cache = @__shapes__
+      shape = cache[keys]
+      return shape if shape
+      return nil if cache.size >= SHAPE_CACHE_LIMIT
+
+      @__shapes_lock__.synchronize do
+        cache[keys.freeze] ||= __create_shape__(keys)
+      end
+    end
+
+    def __create_shape__(keys)
+      ivar_keys = keys.select { |key| IVAR_LOOKUP[key] }
+      overflow_keys = keys - ivar_keys
+      accessor_keys = ivar_keys.reject do |key|
+        method_defined?(key) || private_method_defined?(key) || method_defined?(:"#{key}=")
+      end
+
+      shape = Class.new(self)
+      shape.instance_variable_set(:@__shape__, true)
+      shape.instance_variable_set(:@__base__, __base__ || self)
+      shape.instance_variable_set(:@__overflow_keys__, overflow_keys.freeze)
+      shape.send(:attr_accessor, *accessor_keys) unless accessor_keys.empty?
+
+      # Every interpolated key matched VALID_ATTRIBUTE_NAME, so the eval'd
+      # source can only contain identifier characters. The factory calls
+      # __shape_init__ with the kwargs hash positionally to avoid re-splat
+      # copies; initialize delegates to it for direct shape.new calls.
+      assignments = ivar_keys.map { |key| "  @#{key} = attrs[:#{key}]" }
+      assignments << "  __init_overflow__(attrs)" unless overflow_keys.empty?
+      shape.class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+        # def initialize(**kwargs)
+        #   __shape_init__(kwargs)
+        # end
+        #
+        # def __shape_init__(attrs)
+        #   @name = attrs[:name]
+        #   @email = attrs[:email]
+        #   __init_overflow__(attrs) if any keys need overflow storage
+        # end
+        def initialize(**kwargs)
+          __shape_init__(kwargs)
+        end
+
+        private
+
+        def __shape_init__(attrs)
+        #{assignments.join("\n")}
+        end
+      RUBY
+      shape
+    end
+  end
+
+  # Direct construction path (used when the shape cache is bypassed).
   #
   # @param kwargs [Hash] the attributes to initialize the struct with
   def initialize(**kwargs)
-    @attributes = kwargs.transform_keys(&:to_sym)
+    __init_attributes__(kwargs) unless kwargs.empty?
   end
 
-  # Handles missing methods dynamically, including attribute assignment
+  # Handles attributes added after creation and reads of undefined
+  # attributes, which return `nil` instead of raising `NoMethodError`.
   #
   # @param method_name [Symbol] the name of the missing method
   # @param args [Array] the arguments passed to the missing method
-  # @param block [Proc] an optional block passed to the missing method
   # @return [Object, nil] the value of the attribute, or nil if undefined
   def method_missing(method_name, *args, &_block)
     if method_name.end_with?("=")
-      # Handle dynamic assignment
-      attr_name = method_name[0...-1].to_sym
-      @attributes[attr_name] = args.first
+      self[method_name[0...-1]] = args.first
     else
-      # Handle dynamic retrieval, return nil if attribute does not exist
-      @attributes[method_name]
+      self[method_name]
     end
   end
 
-  # Access attributes using [] with symbol or string
+  # Access attributes using [] with symbol or string.
   #
   # @param key [Symbol, String] the key for the attribute to be retrieved
   # @return [Object, nil] the value of the attribute, or nil if undefined
   def [](key)
-    @attributes[key.to_sym]
+    key = key.to_sym unless key.is_a?(Symbol)
+    if (ivar = IVAR_LOOKUP[key])
+      instance_variable_get(ivar)
+    elsif (overflow = @__overflow__)
+      overflow[key]
+    end
   end
 
-  # Set attributes using [] with symbol or string
+  # Set attributes using [] with symbol or string.
   #
   # @param key [Symbol, String] the key for the attribute to be set
   # @param value [Object] the value to assign to the attribute
   def []=(key, value)
-    @attributes[key.to_sym] = value
+    key = key.to_sym unless key.is_a?(Symbol)
+    if (ivar = IVAR_LOOKUP[key])
+      instance_variable_set(ivar, value)
+    else
+      (@__overflow__ ||= {})[key] = value
+    end
   end
 
-  # Ensures SafeOstruct responds to methods for defined and dynamically assigned attributes.
+  # True for attributes that currently hold a value. Shape attributes also
+  # respond via their real accessor methods.
   #
   # @param method_name [Symbol] the name of the method being checked
   # @param include_private [Boolean] whether to include private methods in the check
-  # @return [Boolean] true if the method is defined or dynamically assigned, otherwise false
+  # @return [Boolean]
   def respond_to_missing?(method_name, include_private = false)
-    @attributes.key?(method_name) || super
+    if (ivar = IVAR_LOOKUP[method_name])
+      instance_variable_defined?(ivar) || super
+    else
+      overflow = @__overflow__
+      (overflow ? overflow.key?(method_name) : false) || super
+    end
   end
 
   # Deletes an attribute from the struct.
@@ -104,17 +229,93 @@ class SafeOstruct
   # @param key [Symbol, String] the key of the attribute to delete
   # @return [Object, nil] the value of the deleted attribute, or nil if the attribute did not exist
   def delete_field(key)
-    @attributes.delete(key.to_sym)
+    key = key.to_sym unless key.is_a?(Symbol)
+    if (ivar = IVAR_LOOKUP[key])
+      remove_instance_variable(ivar) if instance_variable_defined?(ivar)
+    else
+      @__overflow__&.delete(key)
+    end
   end
 
   # Converts the attributes of the SafeOstruct into a hash.
   #
-  # @return [Hash] a hash representation of the attributes, where keys are symbols
-  # and values are the corresponding attribute values. This method provides a way
-  # to easily access the internal state of the SafeOstruct as a standard hash,
-  # facilitating serialization and interoperability with other Ruby classes and
-  # methods that expect a hash input.
+  # @return [Hash] a freshly built hash of the attributes with symbol keys.
+  # Mutating the returned hash does not affect the struct.
   def to_h
-    @attributes
+    hash = {}
+    instance_variables.each do |ivar|
+      next if ivar.start_with?("@__")
+
+      hash[ivar[1..].to_sym] = instance_variable_get(ivar)
+    end
+    overflow = @__overflow__
+    hash.merge!(overflow) if overflow && !overflow.empty?
+    hash
+  end
+
+  # Yields each attribute name and value; returns an Enumerator without a block.
+  #
+  # @yieldparam key [Symbol]
+  # @yieldparam value [Object]
+  # @return [SafeOstruct, Enumerator]
+  def each_pair(&block)
+    pairs = to_h
+    return pairs.each_pair unless block_given?
+
+    pairs.each_pair(&block)
+    self
+  end
+
+  # Extracts a nested value, like Hash#dig.
+  #
+  # @param key [Symbol, String] the first key
+  # @param keys [Array] further keys passed to dig on the value
+  # @return [Object, nil]
+  def dig(key, *keys)
+    value = self[key]
+    keys.empty? ? value : value&.dig(*keys)
+  end
+
+  # Two SafeOstructs are equal when their attributes are equal, regardless
+  # of which shape class backs them.
+  #
+  # @param other [Object]
+  # @return [Boolean]
+  def ==(other)
+    other.is_a?(SafeOstruct) && to_h == other.to_h
+  end
+  alias eql? ==
+
+  # @return [Integer] hash code derived from the attributes
+  def hash
+    to_h.hash
+  end
+
+  # @return [String] readable representation, e.g. #<SafeOstruct name="John">
+  def inspect
+    base = self.class.__base__ || self.class
+    label = base.name || "SafeOstruct"
+    attrs = to_h.map { |key, value| "#{key}=#{value.inspect}" }.join(", ")
+    attrs.empty? ? "#<#{label}>" : "#<#{label} #{attrs}>"
+  end
+  alias to_s inspect
+
+  private
+
+  def __init_attributes__(kwargs)
+    kwargs.each do |key, value|
+      key = key.to_sym unless key.is_a?(Symbol)
+      if (ivar = IVAR_LOOKUP[key])
+        instance_variable_set(ivar, value)
+      else
+        (@__overflow__ ||= {})[key] = value
+      end
+    end
+  end
+
+  def __init_overflow__(kwargs)
+    overflow = {}
+    self.class.__overflow_keys__.each { |key| overflow[key] = kwargs[key] }
+    @__overflow__ = overflow
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_ostruct
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Waqas Ali
@@ -10,12 +10,12 @@ bindir: bin
 cert_chain: []
 date: 2026-07-27 00:00:00.000000000 Z
 dependencies: []
-description: SafeOstruct is a lightweight, dependency-free struct-like class backed
-  by a plain symbol-keyed Hash. It supports dynamic attribute definition via keyword
-  arguments, method-style and hash-style (symbol or string) access, and returns nil
-  instead of raising NoMethodError for undefined attributes. Unlike OpenStruct, it
-  never defines singleton methods, so instantiation stays fast and method caches stay
-  intact.
+description: SafeOstruct is a fast, dependency-free struct-like class with an OpenStruct-style
+  interface. Instances are built on cached per-key-set shape classes with real attr_accessor
+  methods, so attribute reads and writes run at Struct speed (within ~10% of raw Hash
+  access) instead of going through method_missing. It supports dynamic attributes,
+  method-style and hash-style (symbol or string) access, and returns nil instead of
+  raising NoMethodError for undefined attributes.
 email:
 - waqas@sendoso.com
 executables: []
@@ -53,5 +53,5 @@ requirements: []
 rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
-summary: A hash-backed OpenStruct alternative that returns nil for undefined attributes
+summary: A fast OpenStruct alternative that returns nil for undefined attributes
 test_files: []