safe_ostruct 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b350ef819ecad8545a838c5e3a1c1840fbbe7f64c8455a56a0afa304e4e1d7e
+  data.tar.gz: ff69a99e6fba10bf86c54cc360e4ae41c31add767ccd3e080eaa325a754c88b5
+SHA512:
+  metadata.gz: 68b2240672f66147033bc97efcc01b0a06747cf8b89d327236ac445fd1b72005cf40ed759a1127922134e70cb5934771fb4663d9fd4292d6910b5dae8c53a955
+  data.tar.gz: 959d453d08c5ee503883c6279f9c747dff73fe73368c3ef1c9a720356c5532b9064b17f0005b2aaf36b656fa505bbcc73d766fbbca6497b34e8cc812c9772815

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [1.0.0] - 2026-07-27
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Waqas Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,110 @@
+# SafeOstruct
+
+A lightweight, dependency-free `OpenStruct` alternative backed by a plain symbol-keyed `Hash`. 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.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "safe_ostruct"
+```
+
+Or install directly:
+
+```bash
+gem install safe_ostruct
+```
+
+## Usage
+
+```ruby
+require "safe_ostruct" # `require "safe_ostruct"` works too
+
+obj = SafeOstruct.new(name: "John Doe")
+
+# Method-style and hash-style access, with symbols or strings
+obj.name      # => "John Doe"
+obj[:name]    # => "John Doe"
+obj["name"]   # => "John Doe"
+
+# Add attributes dynamically
+obj.address = "123 Main St"
+obj[:city] = "Springfield"
+
+# Undefined attributes return nil, never NoMethodError
+obj.age       # => nil
+obj[:age]     # => nil
+
+# Remove attributes
+obj.delete_field(:address)
+obj.address   # => nil
+
+# Convert to a hash
+obj.to_h      # => { name: "John Doe", city: "Springfield" }
+```
+
+It also works as a `JSON.parse` object class for dot-notation access to parsed JSON:
+
+```ruby
+require "json"
+
+parsed = JSON.parse('{"user": {"name": "Jane"}}', object_class: SafeOstruct)
+parsed.user.name  # => "Jane"
+```
+
+And as a base class for simple result objects:
+
+```ruby
+class ResponseResult < SafeOstruct
+  def success?
+    self[:status] == "success"
+  end
+end
+```
+
+## Behavior notes
+
+These behaviors are intentional and covered by the test suite. They will not change without a major version bump.
+
+- **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.
+
+## 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):
+
+| 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 |
+
+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.
+
+Run the benchmark yourself:
+
+```bash
+bundle exec ruby benchmark/ips.rb
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake   # runs rspec + rubocop
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/safe_ostruct/version.rb

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

data/lib/safe_ostruct.rb

@@ -0,0 +1,120 @@
+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.
+#
+# 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.
+#
+# Key features:
+# - Define attributes dynamically with keyword arguments.
+# - Handle missing methods by returning `nil` instead of raising `NoMethodError`.
+# - 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`.
+#
+# 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'
+#
+#   # 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' }
+#
+# 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.
+#
+class SafeOstruct
+  # Initializes the SafeOstruct with attributes provided as keyword arguments or a hash.
+  #
+  # @param kwargs [Hash] the attributes to initialize the struct with
+  def initialize(**kwargs)
+    @attributes = kwargs.transform_keys(&:to_sym)
+  end
+
+  # Handles missing methods dynamically, including attribute assignment
+  #
+  # @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
+    else
+      # Handle dynamic retrieval, return nil if attribute does not exist
+      @attributes[method_name]
+    end
+  end
+
+  # 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]
+  end
+
+  # 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
+  end
+
+  # Ensures SafeOstruct responds to methods for defined and dynamically assigned attributes.
+  #
+  # @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
+  def respond_to_missing?(method_name, include_private = false)
+    @attributes.key?(method_name) || super
+  end
+
+  # Deletes an attribute from the struct.
+  #
+  # @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)
+  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.
+  def to_h
+    @attributes
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: safe_ostruct
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Waqas Ali
+autorequire:
+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.
+email:
+- waqas@sendoso.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/safe_ostruct.rb
+- lib/safe_ostruct/version.rb
+homepage: https://github.com/wqsaali/safe-ostruct
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/wqsaali/safe-ostruct
+  source_code_uri: https://github.com/wqsaali/safe-ostruct
+  changelog_uri: https://github.com/wqsaali/safe-ostruct/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: A hash-backed OpenStruct alternative that returns nil for undefined attributes
+test_files: []