dotkey 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 59465e04fac7799b3ae896136cf7c2e6d756d3638ce4fd4229b1b69968e42821
+  data.tar.gz: 20ce766129ecf3dab53ada7364949f423ddd2d8f287d1812219de3db733a937e
+SHA512:
+  metadata.gz: 40abb13a263c3e77daedeb909087115539a66488721272105380f3e33b5c0856c1680ba65f8befadbdeeaf04ea9fca3b73ab0734f9bddcde03e6d48a8f7e729d
+  data.tar.gz: 17129e2bc6555e2b9abd4010d07d8e299267d62b2a47e71e59f82dc97d10a55dd16480a4cd1ddbcaa068d3d829540e7929687743ba0b195ce84a32325eafa008

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+## 1.0.0 [UNRELEASED]
+- Initial release

data/LICENSE.md

@@ -0,0 +1,24 @@
+The MIT License (MIT)
+
+This software and documentation is built on previous effort in the Laravel
+project  
+Original work Copyright (c) Taylor Otwell  
+Derivative work Copyright (c) 2024 Simon J
+
+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,284 @@
+# DotKey
+
+DotKey is a Ruby gem that allows you to easily interact with Ruby objects using dot notation.
+
+## Getting started
+
+Add DotKey to your Rails project by adding it to your Gemfile:
+
+```shell
+gem install dotkey
+```
+
+Or using bundler:
+
+```shell
+bundle add dotkey
+```
+
+## Usage
+
+### get
+
+Retrieves a value from a data structure (Hash, Array, or a nested combination) using a dot-delimited key.
+
+```ruby
+data = {a: {b: [1, 2]}, "c" => [{d: 3}, {e: 4}]}
+
+DotKey.get(data, "a")       # => {b: [1, 2]}
+DotKey.get(data, "a.b")     # => [1, 2]
+DotKey.get(data, "a.b.0")   # => 1
+DotKey.get(data, "c.0.d")   # => 3
+```
+
+If any values along the path are `nil`, `nil` is returned. However, trying to traverse something that is not a Hash or Array will cause an error:
+
+```ruby
+# `b.c` is nil so the result is nil
+DotKey.get({b: {}}, "b.c.d")        # => nil
+
+# `c` is not a valid key for an Array, so an error is raised
+DotKey.get({b: []}, "b.c.d")        # => raises DotKey::InvalidTypeError
+
+# `0` is a valid key for an array, but is nil so the result is nil
+DotKey.get({b: []}, "b.0.d")        # => nil
+
+# Strings cannot be traversed so an error is raised
+DotKey.get({a: "a string"}, "a.b")  # => raises DotKey::InvalidTypeError
+```
+
+This behaviour can be disabled by specifying the `raise_on_invalid` parameter:
+
+```ruby
+DotKey.get({b: []}, "b.c.d", raise_on_invalid: false)        # => nil
+DotKey.get({a: "a string"}, "a.b", raise_on_invalid: false)  # => nil
+```
+
+### get_all
+
+Retrieves all matching values from a data structure (Hash, Array, or a nested combination) using a dot-delimited key with wildcards.
+
+`*` and `**` can be used as wildcards for Array items and Hash keys respectively:
+
+```ruby
+data = {a: [{b: 1}, {b: 2, c: 3}], d: [4, 5]}
+
+DotKey.get_all(data, "a.0.b") # => {"a.0.b" => 1}
+
+# Use `*` as a wildcard for arrays
+DotKey.get_all(data, "a.*.b") # => {"a.0.b" => 1, "a.1.b" => 2}
+
+# Use `**` as a wildcard for Hashes
+DotKey.get_all(data, "a.1.**") # => {"a.1.b" => 2, "a.1.c" => 3}
+
+DotKey.get_all(data, "**.*") # => {"a.0" => {b: 1}, "a.1" => {b: 2, c: 3}, "d.0" => 4, "d.1" => 5}
+```
+
+If any values along the path are `nil`, `nil` is returned. However, trying to traverse something that is not a Hash or Array will cause an error:
+
+```ruby
+# `b.c` is nil so the result is nil
+DotKey.get({b: {}}, "b.c.d")        # => nil
+
+# `c` is not a valid key for an Array, so an error is raised
+DotKey.get({b: []}, "b.c.d")        # => raises DotKey::InvalidTypeError
+
+# `0` is a valid key for an array, but is nil so the result is nil
+DotKey.get({b: []}, "b.0.d")        # => nil
+
+# Strings cannot be traversed so an error is raised
+DotKey.get({a: "a string"}, "a.b")  # => raises DotKey::InvalidTypeError
+```
+
+This behaviour can be disabled by specifying the `raise_on_invalid` parameter:
+
+```ruby
+DotKey.get({b: []}, "b.c.d", raise_on_invalid: false)        # => nil
+DotKey.get({a: "a string"}, "a.b", raise_on_invalid: false)  # => nil
+```
+
+Missing values are included in the result as `nil` values, but these can be omitted by specifying the `include_missing` parameter:
+
+```ruby
+data = {a: [{b: 1}, {b: 2, c: 3}], d: 4}
+
+DotKey.get_all(data, "a.*.c")                         # => {"a.0.c" => nil, "a.1.c" => 3}
+DotKey.get_all(data, "a.*.c", include_missing: false) # => {"a.1.c" => 3}
+
+# This behaviour also affects `nil` values from invalid paths
+DotKey.get_all(data, "d.*", raise_on_invalid: false) # => {"d.*" => nil}
+DotKey.get_all(data, "d.*", raise_on_invalid: false, include_missing: false) # => {}
+
+# Note that existing `nil` values are still included even when `include_missing` is false
+DotKey.get_all({a: nil}, "**", include_missing: false) #=> {"a" => nil})
+```
+
+### flatten
+
+Converts a nested structure into a flat Hash, with the dot-delimited path to the value as the key.
+
+```ruby
+DotKey.flatten({a: {b: [1, 2]}, "c" => [{d: 3}, {e: 4}]})
+# => {
+#   "a.b.0" => 1,
+#   "a.b.1" => 2,
+#   "c.0.d" => 3,
+#   "c.1.e" => 4,
+# }
+```
+
+### set!
+
+Sets a value in a data structure (Hash, Array, or a nested combination) using a dot-delimited key.
+
+```ruby
+data = {a: {b: [1]}}
+DotKey.set!(data, "a.b.0", "a")
+DotKey.set!(data, "a.b.1", "b")
+DotKey.set!(data, "c", "d")
+data #=> {a: {b: ["a", "b"]}, :c => "d"}
+```
+
+Intermediate structures are created as needed when traversing a path that includes
+missing elements:
+
+```ruby
+data = {}
+DotKey.set!(data, "a.b.c.0", 42)
+data #=> {a: {b: {c: [42]}}}
+
+DotKey.set!(data, "a.b.c.2", 44)
+data #=> {a: {b: {c: [42, nil, 44]}}}
+```
+
+By default, keys are created as symbols, but string keys can by specified using the
+`string_keys` parameter:
+
+```ruby
+data = {}
+DotKey.set!(data, "a", :symbol)
+DotKey.set!(data, "b", "string", string_keys: true)
+data #=> {a: :symbol, "b" => "string"}
+```
+
+If a key along the path refers to a structure that is neither a Hash nor an Array,
+an error is raised:
+
+```ruby
+data = {a: "string"}
+DotKey.set!(data, "a.b", 42) #=> raises `DotKey::InvalidTypeError`
+```
+
+### delete!
+
+Removes a value from a data structure (Hash, Array, or a nested combination) using a dot-delimited key and returns the deleted value.
+
+```ruby
+data = {a: {b: [1, 2]}, "c" => [{d: 3}, {e: 4}]}
+
+DotKey.delete!(data, "a.b.0")   #=> 1
+data #=> {a: {b: [2]}, "c" => [{d: 3}, {e: 4}]}
+
+DotKey.delete!(data, "c.0.d")   #=> 3
+data #=> {a: {b: [2]}, "c" => [{}, {e: 4}]}
+```
+
+If any values along the path are `nil`, nothing happens and `nil` is returned. However, if a key along the path refers to a structure that is neither a Hash nor an Array, an error is raised:
+
+```ruby
+# `b.c` is nil so the result is nil
+DotKey.delete!({b: {}}, "b.c.d")        #=> nil
+
+# `c` is not a valid key for an Array, so an error is raised
+DotKey.delete!({b: []}, "b.c.d")        #=> raises DotKey::InvalidTypeError
+
+# `0` is a valid key but is nil so the result is nil
+DotKey.delete!({b: []}, "b.0.d")        #=> nil
+
+# Strings cannot be traversed so an error is raised
+DotKey.delete!({a: "a string"}, "a.b")  #=> raises DotKey::InvalidTypeError
+```
+
+This behaviour can be disabled by specifying the `raise_on_invalid` parameter:
+
+```ruby
+DotKey.delete!({b: []}, "b.c.d", raise_on_invalid: false)        #=> nil
+DotKey.delete!({a: "a string"}, "a.b", raise_on_invalid: false)  #=> nil
+```
+
+## Configuration
+
+The default delimiter for keys is a dot, `.`. However, this can be changed to any other String using the `DotKey.delimiter` option:
+
+```ruby
+DotKey.delimiter = "_"
+
+DotKey.get({a: {b: [1]}}, "a_b_0") #=> 1
+DotKey.flatten({a: {b: [1]}}) #=> {"a_b_0" => 1}
+```
+
+## Performance
+
+Due to the parsing of string keys, DotKey won't be the most performant option when accessing data in nested objects:
+
+```ruby
+# Benchmarking DotKey.get vs native alternatives
+object = {a: {b: {c: {d: {e: {f: {g: [[[1]]]}}}}}}}
+
+Benchmark.ips do |bm|
+  bm.report("dotkey") { DotKey.get(object, "a.b.c.d.e.f.g.0.0.0") }
+  bm.report("dig") { object.dig(:a, :b, :c, :d, :e, :f, :g, 0, 0, 0) }
+  bm.report("brackets") { object[:a][:b][:c][:d][:e][:f][:g][0][0][0] }
+  bm.report("fetch") { object.fetch(:a).fetch(:b).fetch(:c).fetch(:d).fetch(:e).fetch(:f).fetch(:g).fetch(0).fetch(0).fetch(0) }
+  bm.compare!
+end
+
+# brackets: 12132728.2 i/s
+#      dig: 10368408.4 i/s - 1.17x  slower
+#    fetch:  6080694.0 i/s - 2.00x  slower
+#   dotkey:   494617.5 i/s - 24.53x  slower (!!)
+```
+
+However, DotKey excels at providing a concise and flexible approach to working with nested data structures:
+it offers customisable handling of missing values and error conditions, while seamlessly supporting
+both string and symbol keys without requiring explicit type conversion.
+
+While much slower than the alternatives, it is still quick and efficient enough for most use cases. In fact, comparing `DotKey.get` again using Rails' HashWithIndifferentAccess, the performance is comparable to using `dig`:
+
+```ruby
+# Benchmarking DotKey.get vs alternatives using HashWithIndifferentAccess
+object = {a: {"b" => {c: {"d" => {e: {"f" => {g: [[[1]]]}}}}}}}
+indifferent = ActiveSupport::HashWithIndifferentAccess.new(
+  {a: {"b" => {c: {"d" => {e: {"f" => {g: [[[1]]]}}}}}}},
+)
+
+Benchmark.ips do |bm|
+  bm.report("dotkey") { DotKey.get(object, "a.b.c.d.e.f.g.0.0.0") }
+  bm.report("indifferent dotkey") { DotKey.get(indifferent, "a.b.c.d.e.f.g.0.0.0") }
+  bm.report("indifferent dig") { indifferent.dig(:a, :b, :c, :d, :e, :f, :g, 0, 0, 0) }
+  bm.report("indifferent brackets") { indifferent[:a][:b][:c][:d][:e][:f][:g][0][0][0] }
+  bm.report("indifferent fetch") { indifferent.fetch(:a).fetch(:b).fetch(:c).fetch(:d).fetch(:e).fetch(:f).fetch(:g).fetch(0).fetch(0).fetch(0) }
+  bm.compare!
+end
+
+# indifferent brackets:  1738761.7 i/s
+#    indifferent fetch:  1026543.3 i/s - 1.69x  slower
+#               dotkey:   547557.6 i/s - 3.18x  slower
+#      indifferent dig:   526314.7 i/s - 3.30x  slower
+#   indifferent dotkey:   477155.6 i/s - 3.64x  slower
+```
+
+The performance for setting values is much more comparable, but with significantly more succinct code:
+
+```
+# brackets set:
+#     431898.9 i/s
+# brackets set with missing intermediate values:
+#     394861.3 i/s - 1.09x  slower
+# dotkey set:
+#     212933.4 i/s - 2.03x  slower
+# dotkey set with missing intermediate values:
+#     168456.3 i/s - 2.56x  slower
+```
+
+See the [performance test suite](test/unit/benchmark_test.rb) for more details.

data/lib/dotkey/dot_key.rb

@@ -0,0 +1,428 @@
+class DotKey
+  class InvalidTypeError < StandardError; end
+
+  class << self
+    attr_writer :delimiter
+
+    def delimiter
+      defined?(@delimiter) ? @delimiter : "."
+    end
+
+    # = \get
+    # Retrieves a value from a data structure (Hash, Array, or a nested combination) using
+    # a dot-delimited key.
+    #
+    #   data = {a: {b: [1, 2]}, "c" => [{d: 3}, {e: 4}]}
+    #
+    #   DotKey.get(data, "a")       #=> {b: [1, 2]}
+    #   DotKey.get(data, "a.b")     #=> [1, 2]
+    #   DotKey.get(data, "a.b.0")   #=> 1
+    #   DotKey.get(data, "c.0.d")   #=> 3
+    #
+    # If any values along the path are <tt>nil</tt>, <tt>nil</tt> is returned. However, if
+    # a key along the path refers to a structure that is neither a Hash nor an Array, an
+    # error is raised.
+    #
+    #   # `b.c` is nil so the result is nil
+    #   DotKey.get({b: {}}, "b.c.d")        #=> nil
+    #
+    #   # `c` is not a valid key for an Array, so an error is raised
+    #   DotKey.get({b: []}, "b.c.d")        #=> raises DotKey::InvalidTypeError
+    #
+    #   # `0` is a valid key but is nil so the result is nil
+    #   DotKey.get({b: []}, "b.0.d")        #=> nil
+    #
+    #   # Strings cannot be traversed so an error is raised
+    #   DotKey.get({a: "a string"}, "a.b")  #=> raises DotKey::InvalidTypeError
+    #
+    # This behaviour can be disabled by specifying the `raise_on_invalid` parameter:
+    #
+    #   DotKey.get({b: []}, "b.c.d", raise_on_invalid: false)        #=> nil
+    #   DotKey.get({a: "a string"}, "a.b", raise_on_invalid: false)  #=> nil
+    #
+    # @param data [Hash,Array] The root data structure
+    # @param key [String,Symbol] A dot-delimited string or symbol representing the path to be resolved.
+    # @param raise_on_invalid [Boolean] A boolean indicating whether to raise an <tt>InvalidTypeError</tt> if a key path cannot be resolved due to an incompatible type. Defaults to <tt>true</tt>.
+    # @return The value at the specified key path. Returns <tt>nil</tt> if any part of the path is missing or nil.
+    # @raise [InvalidTypeError] If the key cannot be resolved due to an invalid type along the path, and <tt>raise_on_invalid</tt> is <tt>true</tt>.
+    def get(data, key, raise_on_invalid: true)
+      key_parts = key.to_s.split(delimiter)
+      current = data
+
+      key_parts.each do |key_part|
+        if current.is_a?(Hash)
+          current = current[key_part] || current[key_part.to_sym]
+        elsif current.is_a?(Array)
+          current = begin
+            current[Integer(key_part)]
+          rescue ArgumentError
+            if raise_on_invalid
+              raise InvalidTypeError.new "Unable to consume key #{key_part} on #{current.class}"
+            end
+          end
+        elsif current.nil?
+          return nil
+        elsif raise_on_invalid
+          raise InvalidTypeError.new "Unable to consume key #{key_part} on #{current.class}"
+        else
+          return nil
+        end
+      end
+
+      current
+    end
+
+    # = \get_all
+    # Retrieves all matching values from a data structure (Hash, Array, or a nested
+    # combination) using a dot-delimited key.
+    #
+    # <tt>*</tt> and <tt>**</tt> can be used as wildcards for Array items and Hash keys
+    # respectively:
+    #
+    #   data = {a: [{b: 1}, {b: 2, c: 3}], d: [4, 5]}
+    #
+    #   DotKey.get_all(data, "a.0.b") #=> {"a.0.b" => 1}
+    #
+    #   # Use `*` as a wildcard for Array indexes
+    #   DotKey.get_all(data, "a.*.b") #=> {"a.0.b" => 1, "a.1.b" => 2}
+    #
+    #   # Use `**` as a wildcard for Hash keys
+    #   DotKey.get_all(data, "a.1.**") #=> {"a.1.b" => 2, "a.1.c" => 3}
+    #
+    #   DotKey.get_all(data, "**.*") #=> {"a.0" => {b: 1}, "a.1" => {b: 2, c: 3}, "d.0" => 4, "d.1" => 5}
+    #
+    # If any values along the path are <tt>nil</tt>, <tt>nil</tt> is returned. However,
+    # if a key along the path refers to a structure that is neither a Hash nor an Array,
+    # an error is raised.
+    #
+    #   # `b.c` is nil so the result is nil
+    #   DotKey.get({b: {}}, "b.c.d")        #=> nil
+    #
+    #   # `c` is not a valid key for an Array, so an error is raised
+    #   DotKey.get({b: []}, "b.c.d")        #=> raises DotKey::InvalidTypeError
+    #
+    #   # `0` is a valid key for an array, but is nil so the result is nil
+    #   DotKey.get({b: []}, "b.0.d")        #=> nil
+    #
+    #   # Strings cannot be traversed so an error is raised
+    #   DotKey.get({a: "a string"}, "a.b")  #=> raises DotKey::InvalidTypeError
+    #
+    # This behaviour can be disabled by specifying the <tt>raise_on_invalid</tt> parameter.
+    #
+    #   DotKey.get({b: []}, "b.c.d", raise_on_invalid: false)        #=> nil
+    #   DotKey.get({a: "a string"}, "a.b", raise_on_invalid: false)  #=> nil
+    #
+    # Missing values are included in the result as <tt>nil</tt> values, but these can be
+    # omitted by specifying the <tt>include_missing</tt> parameter.
+    #
+    #   data = {a: [{b: 1}, {b: 2, c: 3}], d: 4}
+    #
+    #   DotKey.get_all(data, "a.*.c")                         #=> {"a.0.c" => nil, "a.1.c" => 3}
+    #   DotKey.get_all(data, "a.*.c", include_missing: false) #=> {"a.1.c" => 3}
+    #
+    #   # This behaviour also affects `nil` values from invalid paths
+    #   DotKey.get_all(data, "d.*", raise_on_invalid: false) #=> {"d.*" => nil}
+    #   DotKey.get_all(data, "d.*", raise_on_invalid: false, include_missing: false) #=> {}
+    #
+    #   # Note that existing `nil` values are still included even when `include_missing` is false
+    #   DotKey.get_all({a: nil}, "**", include_missing: false) #=> {"a" => nil})
+    #
+    # @param data [Hash,Array] The root data structure
+    # @param key [String,Symbol] A dot-delimited string or symbol representing the path to be resolved. <tt>*</tt> and <tt>**</tt> can be used as wildcards for Array items and Hash keys respectively.
+    # @param include_missing [Boolean] A boolean indicating whether to include missing keys with <tt>nil</tt> values when a part of the key path does not exist. Defaults to <tt>true</tt>.
+    # @param raise_on_invalid [Boolean] A boolean indicating whether to raise an <tt>InvalidTypeError</tt> if a key path cannot be resolved due to an incompatible type. Defaults to <tt>true</tt>.
+    # @return [Hash] A Hash mapping the fully qualified resolved key paths to their corresponding values. If partial matches or missing keys are permitted, values may include <tt>nil</tt>.
+    # @raise [InvalidTypeError] If the key cannot be resolved due to an invalid type along the path, and <tt>raise_on_invalid</tt> is <tt>true</tt>.
+    def get_all(data, key, include_missing: true, raise_on_invalid: true)
+      key_parts = key.to_s.split(delimiter)
+      values = {"" => data}
+
+      key_parts.each do |key|
+        key_as_int = nil
+
+        values = if key == "*"
+          values.each_with_object({}) do |(parent_key, array), object|
+            key_prefix = (parent_key == "") ? "" : "#{parent_key}#{delimiter}"
+            if array.is_a? Array
+              array.each_with_index do |item, index|
+                object["#{key_prefix}#{index}"] = item
+              end
+            elsif raise_on_invalid
+              raise InvalidTypeError.new "Expected #{parent_key} to be an Array, but got #{array.class}"
+            elsif include_missing
+              object["#{key_prefix}*"] = nil
+            end
+          end
+        elsif key == "**"
+          values.each_with_object({}) do |(parent_key, hash), object|
+            key_prefix = (parent_key == "") ? "" : "#{parent_key}#{delimiter}"
+            if hash.is_a? Hash
+              hash.each do |hash_key, item|
+                object["#{key_prefix}#{hash_key}"] = item
+              end
+            elsif raise_on_invalid
+              raise InvalidTypeError.new "Expected #{parent_key} to be a Hash, but got #{hash.class}"
+            elsif include_missing
+              object["#{key_prefix}**"] = nil
+            end
+          end
+        else
+          values.each_with_object({}) do |(parent_key, val), object|
+            key_prefix = (parent_key == "") ? "" : "#{parent_key}#{delimiter}"
+
+            if val.is_a?(Hash)
+              if val.has_key?(key) || val.has_key?(key.to_sym)
+                object["#{key_prefix}#{key}"] = val[key] || val[key.to_sym]
+              elsif include_missing
+                object["#{key_prefix}#{key}"] = nil
+              end
+            elsif val.is_a?(Array) && key_as_int != :invalid
+              begin
+                key_as_int ||= Integer(key)
+
+                if val.length > key_as_int
+                  object["#{key_prefix}#{key}"] = val[key_as_int]
+                elsif include_missing
+                  object["#{key_prefix}#{key}"] = nil
+                end
+              rescue ArgumentError
+                key_as_int = :invalid
+
+                if raise_on_invalid
+                  raise InvalidTypeError.new "Expected #{key} to be an array key for Array #{parent_key}"
+                elsif include_missing
+                  object["#{key_prefix}#{key}"] = nil
+                end
+              end
+            elsif raise_on_invalid
+              if val.is_a?(Array) && key_as_int == :invalid
+                raise InvalidTypeError.new "Expected #{key} to be an array key for Array #{parent_key}"
+              else
+                raise InvalidTypeError.new "Expected #{parent_key} to be a Hash or Array, but got #{val.class}"
+              end
+            elsif include_missing
+              object["#{key_prefix}#{key}"] = nil
+            end
+          end
+        end
+      end
+
+      values
+    end
+
+    # = \flatten
+    # Converts a nested structure into a flat Hash, with the dot-delimited path to the
+    # value as the key.
+    #
+    #   DotKey.flatten({a: {b: [1, 2]}, "c" => [{d: 3}, {e: 4}]})
+    #   #=> {
+    #   #   "a.b.0" => 1,
+    #   #   "a.b.1" => 2,
+    #   #   "c.0.d" => 3,
+    #   #   "c.1.e" => 4,
+    #   # }
+    #
+    # @param data [Hash, Array] The nested structure of Hashes and Arrays to be flattened.
+    # @return [Hash] A flattened Hash representation of the structure where keys are the dot-delimited paths to the values.
+    def flatten(data)
+      _flatten(data, "")
+    end
+
+    private def _flatten(data, prefix)
+      result = {}
+
+      if data.is_a?(Hash)
+        data.each do |key, value|
+          path = (prefix == "") ? key.to_s : "#{prefix}#{delimiter}#{key}"
+          result.merge! _flatten(value, path)
+        end
+      elsif data.is_a?(Array)
+        data.each_with_index do |item, index|
+          path = (prefix == "") ? index.to_s : "#{prefix}#{delimiter}#{index}"
+          result.merge! _flatten(item, path)
+        end
+      else
+        return {prefix => data}
+      end
+
+      result
+    end
+
+    # = \set!
+    # Sets a value in a data structure (Hash, Array, or a nested combination) using a
+    # dot-delimited key.
+    #
+    #  data = {a: {b: [1]}}
+    #  DotKey.set!(data, "a.b.0", "a")
+    #  DotKey.set!(data, "a.b.1", "b")
+    #  DotKey.set!(data, "c", "d")
+    #  data #=> {a: {b: ["a", "b"]}, :c => "d"}
+    #
+    # Intermediate structures are created as needed when traversing a path that includes
+    # missing elements.
+    #
+    #  data = {}
+    #  DotKey.set!(data, "a.b.c.0", 42)
+    #  data #=> {a: {b: {c: [42]}}}
+    #
+    #  DotKey.set!(data, "a.b.c.2", 44)
+    #  data #=> {a: {b: {c: [42, nil, 44]}}}
+    #
+    # By default, keys are created as symbols, but string keys can by specified using the
+    # <tt>string_keys</tt> parameter.
+    #
+    #  data = {}
+    #  DotKey.set!(data, "a", :symbol)
+    #  DotKey.set!(data, "b", "string", string_keys: true)
+    #  data #=> {a: :symbol, "b" => "string"}
+    #
+    # If a key along the path refers to a structure that is neither a Hash nor an Array,
+    # an error is raised.
+    #
+    #  data = {a: "string"}
+    #  DotKey.set!(data, "a.b", 42) #=> raises `DotKey::InvalidTypeError`
+    #
+    # @param data [Hash, Array] The root data structure.
+    # @param key [String, Symbol] A dot-delimited string or symbol representing the path to be set.
+    # @param value [Object] The value to set at the specified key path.
+    # @param string_keys [Boolean] If true, keys will be created as strings
+    # @raise [DotKey::InvalidTypeError] If the key cannot be resolved due to an invalid type along the path.
+    def set!(data, key, value, string_keys: false)
+      key_parts = key.to_s.split(delimiter)
+      current = data
+
+      key_parts.each_with_index do |next_key, i|
+        break if i == key_parts.length - 1
+
+        if current.is_a?(Hash)
+          next_value = current[next_key] || current[next_key.to_sym]
+        elsif current.is_a?(Array) && next_key.match?(/\A\d+\z/)
+          next_key = begin
+            Integer(next_key)
+          rescue ArgumentError
+            raise InvalidTypeError.new "Unable to consume key #{next_key}, expecting an integer"
+          end
+
+          next_value = current[next_key]
+        else
+          raise InvalidTypeError.new "Unable to consume key #{next_key}, expecting a Hash or Array, but got #{current.class}"
+        end
+
+        current = if next_value.is_a?(Hash) || next_value.is_a?(Array)
+          next_value
+        elsif next_value.nil?
+          if key_parts[i + 1].match?(/\A\d+\z/)
+            (current[(next_key.is_a?(Integer) || string_keys) ? next_key : next_key.to_sym] = [])
+          else
+            (current[(next_key.is_a?(Integer) || string_keys) ? next_key : next_key.to_sym] = {})
+          end
+        else
+          raise InvalidTypeError.new "Invalid type for key #{next_key}, expecting a Hash, Array or nil, but got #{next_value.class}"
+        end
+      end
+
+      last_key = key_parts.last
+      if current.is_a?(Hash)
+        last_key = if string_keys
+          current.has_key?(last_key.to_sym) ? last_key.to_sym : last_key
+        else
+          current.has_key?(last_key) ? last_key : last_key.to_sym
+        end
+
+        current[last_key] = value
+      elsif current.is_a?(Array)
+        next_key = begin
+          Integer(last_key)
+        rescue ArgumentError
+          raise InvalidTypeError.new "Unable to consume key #{last_key}, expecting an integer for Array index"
+        end
+
+        current[next_key] = value
+      else
+        raise InvalidTypeError.new "Unable to consume key #{last_key}, expecting a Hash or Array, but got #{current.class}"
+      end
+    end
+
+    # = \delete!
+    # Removes a value from a data structure (Hash, Array, or a nested combination) using
+    # a dot-delimited key and returns the deleted value.
+    #
+    #   data = {a: {b: [1, 2]}, "c" => [{d: 3}, {e: 4}]}
+    #
+    #   DotKey.delete!(data, "a.b.0")   #=> 1
+    #   data #=> {a: {b: [2]}, "c" => [{d: 3}, {e: 4}]}
+    #
+    #   DotKey.delete!(data, "c.0.d")   #=> 3
+    #   data #=> {a: {b: [2]}, "c" => [{}, {e: 4}]}
+    #
+    # If any values along the path are <tt>nil</tt>, nothing happens and <tt>nil</tt> is
+    # returned. However, if a key along the path refers to a structure that is neither a
+    # Hash nor an Array, an error is raised.
+    #
+    #   # `b.c` is nil so the result is nil
+    #   DotKey.delete!({b: {}}, "b.c.d")        #=> nil
+    #
+    #   # `c` is not a valid key for an Array, so an error is raised
+    #   DotKey.delete!({b: []}, "b.c.d")        #=> raises DotKey::InvalidTypeError
+    #
+    #   # `0` is a valid key but is nil so the result is nil
+    #   DotKey.delete!({b: []}, "b.0.d")        #=> nil
+    #
+    #   # Strings cannot be traversed so an error is raised
+    #   DotKey.delete!({a: "a string"}, "a.b")  #=> raises DotKey::InvalidTypeError
+    #
+    # This behaviour can be disabled by specifying the `raise_on_invalid` parameter:
+    #
+    #   DotKey.delete!({b: []}, "b.c.d", raise_on_invalid: false)        #=> nil
+    #   DotKey.delete!({a: "a string"}, "a.b", raise_on_invalid: false)  #=> nil
+    #
+    # @param data [Hash,Array] The root data structure
+    # @param key [String,Symbol] A dot-delimited string or symbol representing the path to the value to be deleted.
+    # @param raise_on_invalid [Boolean] A boolean indicating whether to raise an <tt>InvalidTypeError</tt> if a key path cannot be resolved due to an incompatible type. Defaults to <tt>true</tt>.
+    # @return The deleted value at the specified key path. Returns <tt>nil</tt> if any part of the path is missing or nil.
+    # @raise [InvalidTypeError] If the key cannot be resolved due to an invalid type along the path, and <tt>raise_on_invalid</tt> is <tt>true</tt>.
+    def delete!(data, key, raise_on_invalid: true)
+      key_parts = key.to_s.split(delimiter)
+      current = data
+
+      key_parts.each_with_index do |key_part, i|
+        break if i == key_parts.length - 1
+
+        if current.is_a?(Hash)
+          current = current[key_part] || current[key_part.to_sym]
+        elsif current.is_a?(Array)
+          current = begin
+            current[Integer(key_part)]
+          rescue ArgumentError
+            if raise_on_invalid
+              raise InvalidTypeError.new "Expected #{key_part} to be an array key"
+            end
+          end
+        elsif current.nil?
+          return nil
+        elsif raise_on_invalid
+          raise InvalidTypeError.new "Unable to consume key #{key_part} on #{current.class}"
+        else
+          return nil
+        end
+      end
+
+      last_key = key_parts.last
+      if current.is_a?(Hash)
+        current.delete(current.has_key?(last_key) ? last_key : last_key.to_sym)
+      elsif current.is_a?(Array)
+        begin
+          current.delete_at Integer(last_key)
+        rescue ArgumentError
+          if raise_on_invalid
+            raise InvalidTypeError.new "Expected #{last_key} to be an array key"
+          end
+        end
+      elsif current.nil?
+        nil
+      elsif raise_on_invalid
+        raise InvalidTypeError.new "Unable to consume key #{last_key} on #{current.class}"
+      end
+    end
+  end
+end

data/lib/dotkey.rb

@@ -0,0 +1 @@
+require "dotkey/dot_key"

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: dotkey
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Simon J
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-05-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.49'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.49'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+description: A series of utility methods allowing you to easily interact with Ruby
+  objects using dot notation
+email: 2857218+mwnciau@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- lib/dotkey.rb
+- lib/dotkey/dot_key.rb
+homepage: https://rubygems.org/gems/dotkey
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/mwnciau/dotkey
+  changelog_uri: https://github.com/mwnciau/dotkey/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/mwnciau/dotkey
+  bug_tracker_uri: https://github.com/mwnciau/dotkey/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Interact with object using dot notation
+test_files: []