everythingrb 0.2.5 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 330f80c66964fd22cd85850c251963ea372957a2b3190f4abcb5d0f3346989f7
-  data.tar.gz: f28ebe4ab45e0bb7f1e68f2553af302d6ab2dfaa0509bc3d73615a84330b6d1e
+  metadata.gz: 747441fc1a0c8be071a4465edb190dead79eea7195b66b262976e8ae91b6bc0f
+  data.tar.gz: 491c3bc6c22bc02495425fecfb51166c8982d86ad0eede1b10980e2bf040b705
 SHA512:
-  metadata.gz: ae50b585bb625724ca3e7ae917074fef6ceb25278818c88965aa10ccfae42e067b2716fc36b2f4da0d2cd4b4228b764166c12a43c212c7b44b3874ebe00aa071
-  data.tar.gz: 5558f7dfe032d20489d7accf298eb889ffb22cd4a215509e4d2fd90fa35c23eebefa95ca2170695d4b82a637eb2583daa5a3b11b1660b9a9ccb1fa3b9dc5dcf9
+  metadata.gz: f6605c462aeeb634fe3342a3befb424fe3a67f31059f486d4c835a3670192962a44f6237f51947629cbe1a27d7a21579c03a48f9c98e22f155821cdb62f1e8c1
+  data.tar.gz: e6d2ce8fca0b90b513c686dfc44f8010cfb2aca9cc3be84cdbd08c6fccbbac49727ffbe42805f5a0789496df7b3f68ace624b7c201b30f5ee5305be16af485fa

data/CHANGELOG.md

@@ -23,6 +23,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.3.1] - 12025-04-09
+
+### Added
+
+### Changed
+
+- Fixed `Hash#value_where` error when nothing is found
+
+### Removed
+
+## [0.3.0] - 12025-04-09
+
+### Added
+
+- Added `Array#to_or_sentence`, creates a sentence with "or" connector between items
+- Added `#with_key` method to `Hash#transform_values` and `Hash#transform_values!`, grants access to both keys and values during transformations
+- Added `Array#to_deep_h` and `Hash#to_deep_h`, recursively converts underlying values to hashes
+- Added `Enumerable#group_by_key`, group an array of hashes by their keys
+- Added `Hash#new_nested_hash`, creates a new Hash that automatically initializes the value to a hash
+- Added `Hash#value_where` and `Hash#values_where`, easily find values in a hash based on key-value conditions
+
+### Changed
+
+### Removed
+
 ## [0.2.5] - 12025-03-29
 
 ### Added
@@ -124,7 +149,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Added alias `each` to `each_pair` in OpenStruct for better enumerable compatibility
 
-[unreleased]: https://github.com/itsthedevman/everythingrb/compare/v0.2.5...HEAD
+[unreleased]: https://github.com/itsthedevman/everythingrb/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/itsthedevman/everythingrb/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/itsthedevman/everythingrb/compare/v0.2.5...v0.3.0
 [0.2.5]: https://github.com/itsthedevman/everythingrb/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/itsthedevman/everythingrb/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/itsthedevman/everythingrb/compare/v0.2.2...v0.2.3

data/README.md

@@ -4,97 +4,52 @@
 ![Ruby Version](https://img.shields.io/badge/ruby-3.3.7-ruby)
 [![Tests](https://github.com/itsthedevman/everythingrb/actions/workflows/main.yml/badge.svg)](https://github.com/everythingrb/sortsmith/actions/workflows/main.yml)
 
-Super handy extensions to Ruby core classes that you never knew you needed until now. Write more expressive, readable, and maintainable code with less boilerplate.
+Super handy extensions to Ruby core classes that make your code more expressive, readable, and fun to write.
 
-## Looking for a Software Engineer?
-
-I'm currently looking for opportunities where I can tackle meaningful problems and help build reliable software while mentoring the next generation of developers. If you're looking for a senior engineer with full-stack Rails expertise and a passion for clean, maintainable code, let's talk!
-
-[bryan@itsthedevman.com](mailto:bryan@itsthedevman.com)
+```ruby
+# Instead of this:
+users = [{ name: "Alice", role: "admin" }, { name: "Bob", role: "user" }]
+admin_names = users.select { |u| u[:role] == "admin" }.map { |u| u[:name] }.join(", ")
 
-# Table of Contents
-
-- [Introduction](#introduction)
-- [Compatibility](#compatibility)
-- [Installation](#installation)
-- [Features](#features)
-  - [Data Structure Conversions](#data-structure-conversions)
-  - [Collection Processing](#collection-processing)
-  - [JSON & String Handling](#json--string-handling)
-  - [Object Freezing](#object-freezing)
-  - [Array Trimming](#array-trimming)
-  - [Predicate Methods](#predicate-methods)
-- [Core Extensions](#core-extensions)
-  - [Array](#array)
-  - [Enumerable](#enumerable)
-  - [Hash](#hash)
-  - [Module](#module)
-  - [OpenStruct](#openstruct)
-  - [String](#string)
-  - [Symbol](#symbol)
-- [Advanced Usage](#advanced-usage)
-- [Requirements](#requirements)
-- [Contributing](#contributing)
-- [License](#license)
-- [Changelog](#changelog)
-- [Credits](#credits)
-
-Also see: [API Documentation](https://itsthedevman.com/docs/everythingrb)
-
-## Introduction
-
-EverythingRB adds powerful, intuitive extensions to Ruby's core classes that help you write cleaner, more expressive code. It focuses on common patterns that typically require multiple method calls or temporary variables, turning them into single fluid operations.
-
-Whether you're transforming data, working with JSON, or building complex object structures, EverythingRB makes your code more readable and maintainable with minimal effort.
-
-## Compatibility
-
-Currently tested on:
-- MRI Ruby 3.2+
-- NixOS (see `flake.nix` for details)
+# Write this:
+users.join_map(", ") { |u| u[:name] if u[:role] == "admin" }
+```
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
 ```ruby
+# In your Gemfile
 gem "everythingrb"
-```
 
-And then execute:
-
-```bash
-$ bundle install
+# Or install manually
+gem install everythingrb
 ```
 
-Or install it yourself as:
-
-```bash
-$ gem install everythingrb
-```
+## What's Included
 
-## Features
+EverythingRB extends Ruby's core classes with intuitive methods that simplify common patterns.
 
 ### Data Structure Conversions
 
-Easily convert between different Ruby data structures:
+Convert between data structures with ease:
 
 ```ruby
-# Convert any hash to an OpenStruct, Struct, or Data (immutable) object
+# Convert hashes to more convenient structures
 config = { server: { host: "example.com", port: 443 } }.to_ostruct
 config.server.host  # => "example.com"
 
 # Parse JSON directly to your preferred structure
 '{"user":{"name":"Alice"}}'.to_istruct.user.name  # => "Alice"
-'{"items":[1,2,3]}'.to_struct.items  # => [1, 2, 3]
 ```
 
+**Extensions:** `to_struct`, `to_ostruct`, `to_istruct`, `to_h`, `to_deep_h`
+
 ### Collection Processing
 
-Process collections with elegant, chainable methods:
+Extract and transform data elegantly:
 
 ```ruby
-# Extract specific data from arrays of hashes in one step
+# Extract data from arrays of hashes in one step
 users = [{ name: "Alice", roles: ["admin"] }, { name: "Bob", roles: ["user"] }]
 users.key_map(:name)  # => ["Alice", "Bob"]
 users.dig_map(:roles, 0)  # => ["admin", "user"]
@@ -102,27 +57,16 @@ users.dig_map(:roles, 0)  # => ["admin", "user"]
 # Filter, map, and join in a single operation
 [1, 2, nil, 3, 4].join_map(" | ") { |n| "Item #{n}" if n&.odd? }
 # => "Item 1 | Item 3"
-```
-
-### JSON & String Handling
-
-Work with JSON and strings more naturally:
-
-```ruby
-# Parse JSON with symbolized keys
-'{"name": "Alice"}'.to_h  # => { name: "Alice" }
 
-# Recursively parse nested JSON strings
-nested = '{"user":"{\"profile\":\"{\\\"name\\\":\\\"Bob\\\"}\"}"}'
-nested.to_deep_h  # => { user: { profile: { name: "Bob" } } }
-
-# Format strings with quotes
-"hello".with_quotes  # => "\"hello\""
+# With ActiveSupport loaded, join arrays in natural language with "or"
+["red", "blue", "green"].to_or_sentence  # => "red, blue, or green"
 ```
 
-### Object Freezing
+**Extensions:** `join_map`, `key_map`, `dig_map`, `to_or_sentence`, `group_by_key`
+
+### Object Protection
 
-Freeze nested structures with a single call:
+Prevent unwanted modifications with a single call:
 
 ```ruby
 config = {
@@ -134,429 +78,71 @@ config = {
 
 # Everything is frozen!
 config.frozen?  # => true
-config[:api].frozen?  # => true
-config[:api][:endpoints].frozen?  # => true
 config[:api][:endpoints][0].frozen?  # => true
 ```
 
-### Array Trimming
+**Extensions:** `deep_freeze`
 
-Clean up array boundaries without losing internal structure:
+### Hash Convenience
 
-```ruby
-# Remove nil values from the beginning or end
-[nil, nil, 1, nil, 2, nil, nil].trim_nils  # => [1, nil, 2]
-
-# With ActiveSupport, remove any blank values (nil, "", etc.)
-[nil, "", 1, "", 2, nil, ""].trim_blanks  # => [1, "", 2]
-
-# Only trim from one end if needed
-[nil, nil, 1, 2, 3].compact_prefix  # => [1, 2, 3]
-[1, 2, 3, nil, nil].compact_suffix  # => [1, 2, 3]
-```
-
-### Predicate Methods
-
-Create boolean accessors with minimal code:
-
-```ruby
-class User
-  attr_accessor :admin, :verified
-  attr_predicate :admin, :verified
-end
-
-user = User.new
-user.admin = true
-user.admin?  # => true
-user.verified?  # => false
-
-# Works with Struct and Data objects too
-Person = Struct.new(:active)
-Person.attr_predicate(:active)
-
-person = Person.new(true)
-person.active?  # => true
-```
-
-**ActiveSupport Integration:** When ActiveSupport is loaded, predicate methods automatically use `present?` instead of just checking truthiness:
+Work with hashes more intuitively:
 
 ```ruby
-# With ActiveSupport loaded
-class Product
-  attr_accessor :tags, :category
-  attr_predicate :tags, :category
-end
-
-product = Product.new
-product.tags = []
-product.tags?  # => false (empty array is not "present")
+# Create deeply nested structures without initialization
+stats = Hash.new_nested_hash
+stats[:server][:region][:us_east][:errors] << "Connection timeout"
+# No need to initialize each level first!
 
-product.tags = ["sale"]
-product.tags?  # => true (non-empty array is "present")
+# Transform values with access to keys
+users.transform_values.with_key { |k, v| "User #{k}: #{v[:name]}" }
 
-product.category = ""
-product.category?  # => false (blank string is not "present")
+# Find values based on conditions
+users.values_where { |k, v| v[:role] == "admin" }
 ```
 
-## Core Extensions
+**Extensions:** `new_nested_hash`, `with_key`, `value_where`, `values_where`
 
-### Array
+### Array Cleaning
 
-#### `join_map`
-Combines `filter_map` and `join` operations in one convenient method. Optionally provides the index to the block.
+Clean up array boundaries while preserving internal structure:
 
 ```ruby
-# Without index
-[1, 2, nil, 3].join_map(" ") { |n| n&.to_s if n&.odd? }
-# => "1 3"
-
-# With index
-["a", "b", "c"].join_map(", ", with_index: true) { |char, i| "#{i}:#{char}" }
-# => "0:a, 1:b, 2:c"
-
-# Default behavior without block
-[1, 2, nil, 3].join_map(", ")
-# => "1, 2, 3"
-```
-
-#### `key_map`
-Extracts a specific key from each hash in an array.
-
-```ruby
-users = [
-  { name: "Alice", age: 30 },
-  { name: "Bob", age: 25 }
-]
-
-users.key_map(:name)
-# => ["Alice", "Bob"]
-```
-
-#### `dig_map`
-Extracts nested values from each hash in an array using the `dig` method.
-
-```ruby
-data = [
-  { user: { profile: { name: "Alice" } } },
-  { user: { profile: { name: "Bob" } } }
-]
-
-data.dig_map(:user, :profile, :name)
-# => ["Alice", "Bob"]
-```
-
-#### `compact_prefix` / `compact_suffix` / `trim_nils`
-Remove nil values from the beginning, end, or both ends of an array without touching interior nil values.
-
-```ruby
-[nil, nil, 1, nil, 2, nil, nil].compact_prefix
-# => [1, nil, 2, nil, nil]
-
-[1, nil, 2, nil, nil].compact_suffix
-# => [1, nil, 2]
-
-[nil, nil, 1, nil, 2, nil, nil].trim_nils
-# => [1, nil, 2]
-```
-
-#### `compact_blank_prefix` / `compact_blank_suffix` / `trim_blanks` (with ActiveSupport)
-Remove blank values (nil, empty strings, etc.) from the beginning, end, or both ends of an array.
-
-```ruby
-[nil, "", 1, "", 2, nil, ""].compact_blank_prefix
-# => [1, "", 2, nil, ""]
-
-[nil, "", 1, "", 2, nil, ""].compact_blank_suffix
-# => [nil, "", 1, "", 2]
-
-[nil, "", 1, "", 2, nil, ""].trim_blanks
-# => [1, "", 2]
-```
-
-#### `deep_freeze`
-Recursively freezes an array and all of its nested elements.
-
-```ruby
-array = ["hello", { name: "Alice" }, [1, 2, 3]]
-array.deep_freeze
-# => All elements and nested structures are now frozen
-```
-
-### Enumerable
-
-#### `join_map`
-Combines filtering, mapping and joining operations into one convenient method.
-
-```ruby
-# Basic usage with arrays
-[1, 2, nil, 3].join_map(", ") { |n| n&.to_s if n&.odd? }
-# => "1, 3"
-
-# Works with any Enumerable
-(1..10).join_map(" | ") { |n| "num#{n}" if n.even? }
-# => "num2 | num4 | num6 | num8 | num10"
-
-# Supports with_index option
-%w[a b c].join_map("-", with_index: true) { |char, i| "#{i}:#{char}" }
-# => "0:a-1:b-2:c"
-```
-
-### Hash
-
-#### `to_struct`
-Recursively converts a hash into a Struct, including nested hashes and arrays.
-
-```ruby
-hash = { user: { name: "Alice", roles: ["admin", "user"] } }
-struct = hash.to_struct
-struct.class # => Struct
-struct.user.name # => "Alice"
-struct.user.roles # => ["admin", "user"]
-```
-
-#### `to_ostruct`
-Recursively converts a hash into an OpenStruct, including nested hashes and arrays.
-
-```ruby
-hash = { config: { api_key: "secret", endpoints: ["v1", "v2"] } }
-config = hash.to_ostruct
-config.class # => OpenStruct
-config.config.api_key # => "secret"
-```
-
-#### `to_istruct`
-Recursively converts a hash into an immutable Data structure.
-
-```ruby
-hash = { person: { name: "Bob", age: 30 } }
-data = hash.to_istruct
-data.class # => Data
-data.person.name # => "Bob"
-```
-
-#### `join_map`
-Similar to Array#join_map but operates on hash values.
+# Remove nil values from the beginning/end
+[nil, nil, 1, nil, 2, nil, nil].trim_nils  # => [1, nil, 2]
 
-```ruby
-{ a: 1, b: 2, c: nil, d: 3 }.join_map(" ") { |k, v| [k, v] if v }
-# => "a 1 b 2 d 3"
+# With ActiveSupport, remove blank values
+[nil, "", 1, "", 2, nil, ""].trim_blanks  # => [1, "", 2]
 ```
 
-#### `deep_freeze`
-Recursively freezes a hash and all of its nested values.
+**Extensions:** `trim_nils`, `compact_prefix`, `compact_suffix`, `trim_blanks` (with ActiveSupport)
 
-```ruby
-hash = { user: { name: "Alice", roles: ["admin", "user"] } }
-hash.deep_freeze
-# => Hash and all nested structures are now frozen
-```
+### Boolean Methods
 
-### Module
-
-#### `attr_predicate`
-Creates predicate (boolean) methods for instance variables.
+Create predicate methods with minimal code:
 
 ```ruby
 class User
-  attr_writer :admin
-  attr_predicate :admin, :active
+  attr_accessor :admin
+  attr_predicate :admin
 end
 
 user = User.new
-user.active? # => false
 user.admin = true
-user.admin? # => true
-```
-
-### OpenStruct
-
-#### `each`
-Alias for `each_pair`.
-
-```ruby
-struct = OpenStruct.new(a: 1, b: 2)
-struct.each { |key, value| puts "#{key}: #{value}" }
-```
-
-#### `map`
-Maps over OpenStruct entries.
-
-```ruby
-struct = OpenStruct.new(a: 1, b: 2)
-struct.map { |key, value| [key, value * 2] }
-# => [[:a, 2], [:b, 4]]
-```
-
-#### `filter_map`
-Combines `map` and `compact` operations in one convenient method.
-
-```ruby
-struct = OpenStruct.new(a: 1, b: nil, c: 2)
-struct.filter_map { |key, value| value * 2 if value }
-# => [2, 4]
-```
-
-#### `join_map`
-Combines `filter_map` and `join` operations in one convenient method.
-
-```ruby
-config = OpenStruct.new(
-  alice: {roles: ["admin"]},
-  bob: {roles: ["user"]},
-  carol: {roles: ["admin"]}
-)
-
-config.join_map(", ") { |key, value| key if value[:roles].include?("admin") }
-# => "alice, carol"
-```
-
-### String
-
-#### `to_h` / `to_a`
-Parses JSON string into a Ruby Hash or Array.
-
-```ruby
-'{"name": "Alice"}'.to_h
-# => {name: "Alice"}
-
-'["Alice"]'.to_h # Or you can use #to_a for different readability
-# => ["Alice"]
-```
-
-#### `to_istruct`
-Parses JSON string into an immutable Data structure.
-
-```ruby
-'{"user": {"name": "Alice"}}'.to_istruct
-# => #<data user=#<data name="Alice">>
-```
-
-#### `to_ostruct`
-Parses JSON string into an OpenStruct.
-
-```ruby
-'{"user": {"name": "Alice"}}'.to_ostruct
-# => #<OpenStruct user=#<OpenStruct name="Alice">>
-```
-
-#### `to_struct`
-Parses JSON string into a Struct.
-
-```ruby
-'{"user": {"name": "Alice"}}'.to_struct
-# => #<struct user=#<struct name="Alice">>
-```
-
-#### `to_deep_h`
-Recursively parses nested JSON strings within a structure.
-
-```ruby
-nested_json = {
-  users: [
-    {name: "Alice", roles: ["admin", "user"]}.to_json,
-  ]
-}.to_json
-
-nested_json.to_deep_h
-# => {users: [{name: "Alice", roles: ["admin", "user"]}]}
-```
-
-#### `with_quotes` / `in_quotes`
-Wraps the string in double quotes
-
-```ruby
-"Hello World".with_quotes
-# => "\"Hello World\""
-```
-
-### Symbol
-
-#### `with_quotes` / `in_quotes`
-Wraps the symbol in double quotes
-
-```ruby
-:hello_world.with_quotes
-# => :"\"hello_world\""
-```
-
-## Advanced Usage
-
-See how EverythingRB transforms your code from verbose to elegant:
-
-### Extracting Data from Nested JSON
-
-**Before:**
-```ruby
-# Standard Ruby approach
-json_data = '[{"user":{"name":"Alice","role":"admin"}},{"user":{"name":"Bob","role":"guest"}}]'
-
-parsed_data = JSON.parse(json_data, symbolize_names: true)
-names = parsed_data.map { |item| item[:user][:name] }
-result = names.join(", ")
-# => "Alice, Bob"
-```
-
-**After:**
-```ruby
-# With EverythingRB
-json_data = '[{"user":{"name":"Alice","role":"admin"}},{"user":{"name":"Bob","role":"guest"}}]'
-result = json_data.to_a.dig_map(:user, :name).join(", ")
-# => "Alice, Bob"
-```
-
-### Freezing Nested Configurations
-
-**Before:**
-```ruby
-# Standard Ruby approach
-config_json = File.read("config.json")
-config = JSON.parse(config_json, symbolize_names: true)
-
-deep_freeze = lambda do |obj|
-  case obj
-  when Hash
-    obj.each_value { |v| deep_freeze.call(v) }
-    obj.freeze
-  when Array
-    obj.each { |v| deep_freeze.call(v) }
-    obj.freeze
-  else
-    obj.freeze
-  end
-end
+user.admin?  # => true
 
-frozen_config = deep_freeze.call(config)
-```
+# Works with Data objects too!
+Person = Data.define(:active)
+Person.attr_predicate(:active)
 
-**After:**
-```ruby
-# With EverythingRB
-config_json = File.read("config.json")
-frozen_config = config_json.to_h.deep_freeze
+person = Person.new(active: false)
+person.active? # => false
 ```
 
-### Filtering and Formatting Nested Collections
+**Extensions:** `attr_predicate`
 
-**Before:**
-```ruby
-# Standard Ruby approach
-users_json = '[{"user":{"name":"Alice","admin":true,"active":true}},{"user":{"name":"Bob","admin":true,"active":false}}]'
-
-users = JSON.parse(users_json, symbolize_names: true)
-active_admins = users.map { |u| u[:user] }.select { |u| u[:admin] && u[:active] }
-admin_names = active_admins.map { |u| u[:name] }.join(", ")
-# => "Alice"
-```
+## Full Documentation
 
-**After:**
-```ruby
-# With EverythingRB
-users_json = '[{"user":{"name":"Alice","admin":true,"active":true}},{"user":{"name":"Bob","admin":true,"active":false}}]'
-admin_names = users_json.to_a.key_map(:user).join_map(", ") do |user|
-  user[:name] if user[:admin] && user[:active]
-end
-# => "Alice"
-```
+For complete method listings, examples, and detailed usage, see the [API Documentation](https://itsthedevman.com/docs/everythingrb).
 
 ## Requirements
 
@@ -564,22 +150,14 @@ end
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b feature/my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin feature/my-new-feature`)
-5. Create new Pull Request
-
-Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
+Bug reports and pull requests are welcome! This project is intended to be a safe, welcoming space for collaboration.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
-
-## Changelog
+[MIT License](LICENSE.txt)
 
-See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
+## Looking for a Software Engineer?
 
-## Credits
+I'm currently looking for opportunities where I can tackle meaningful problems and help build reliable software while mentoring the next generation of developers. If you're looking for a senior engineer with full-stack Rails expertise and a passion for clean, maintainable code, let's talk!
 
-- Author: Bryan "itsthedevman"
+[bryan@itsthedevman.com](mailto:bryan@itsthedevman.com)

data/lib/everythingrb/core/array.rb

@@ -93,6 +93,10 @@ class Array
   #   ["hello", { name: "Alice" }, [1, 2, 3]].deep_freeze
   #   # => All elements and nested structures are now frozen
   #
+  # @note CAUTION: Be careful when freezing collections that contain class objects
+  #   or singleton instances - this will freeze those classes/objects globally!
+  #   Only use deep_freeze on pure data structures you want to make immutable.
+  #
   def deep_freeze
     each { |v| v.respond_to?(:deep_freeze) ? v.deep_freeze : v.freeze }
     freeze
@@ -177,5 +181,73 @@ class Array
     def trim_blanks
       compact_blank_prefix.compact_blank_suffix
     end
+
+    #
+    # Joins array elements into a sentence with "or" connector
+    #
+    # Similar to ActiveSupport's #to_sentence but uses "or" instead of "and"
+    # as the joining word between elements.
+    #
+    # @param options [Hash] Options to pass to #to_sentence
+    #
+    # @return [String] Array elements joined in sentence form with "or" connector
+    #
+    # @example Basic usage
+    #   ["red", "blue", "green"].to_or_sentence
+    #   # => "red, blue, or green"
+    #
+    # @example With only two elements
+    #   ["yes", "no"].to_or_sentence
+    #   # => "yes or no"
+    #
+    def to_or_sentence(options = {})
+      options = options.reverse_merge(last_word_connector: ", or ", two_words_connector: " or ")
+      to_sentence(options)
+    end
+  end
+
+  #
+  # Recursively converts all elements that respond to #to_h
+  #
+  # Maps over the array and calls #to_deep_h on any Hash/String elements,
+  # #to_h on any objects that respond to it, and handles nested arrays.
+  #
+  # @return [Array] A new array with all convertible elements deeply converted
+  #
+  # @example Converting arrays with mixed object types
+  #   users = [
+  #     {name: "Alice", roles: ["admin"]},
+  #     OpenStruct.new(name: "Bob", active: true),
+  #     Data.define(:name).new(name: "Carol")
+  #   ]
+  #   users.to_deep_h
+  #   # => [
+  #   #      {name: "Alice", roles: ["admin"]},
+  #   #      {name: "Bob", active: true},
+  #   #      {name: "Carol"}
+  #   #    ]
+  #
+  # @example With nested arrays and JSON strings
+  #   data = [
+  #     {profile: '{"level":"expert"}'},
+  #     [OpenStruct.new(id: 1), OpenStruct.new(id: 2)]
+  #   ]
+  #   data.to_deep_h
+  #   # => [{profile: {level: "expert"}}, [{id: 1}, {id: 2}]]
+  #
+  def to_deep_h
+    map do |value|
+      case value
+      when Hash
+        value.to_deep_h
+      when Array
+        value.to_deep_h
+      when String
+        # If the string is not valid JSON, #to_deep_h will return `nil`
+        value.to_deep_h || value
+      else
+        value.respond_to?(:to_h) ? value.to_h : value
+      end
+    end
   end
 end

data/lib/everythingrb/core/enumerable.rb

@@ -44,4 +44,49 @@ module Enumerable
       filter_map(&block).join(join_with)
     end
   end
+
+  #
+  # Groups elements by a given key or nested keys
+  #
+  # @param keys [Array<Symbol, String>] The key(s) to group by
+  #
+  # @yield [value] Optional block to transform the key value before grouping
+  # @yieldparam value [Object] The value at the specified key(s)
+  # @yieldreturn [Object] The transformed value to use as the group key
+  #
+  # @return [Hash] A hash where keys are the grouped values and values are arrays of elements
+  #
+  # @example Group by a single key
+  #   users = [
+  #     {name: "Alice", role: "admin"},
+  #     {name: "Bob", role: "user"},
+  #     {name: "Charlie", role: "admin"}
+  #   ]
+  #   users.group_by_key(:role)
+  #   # => {"admin"=>[{name: "Alice", role: "admin"}, {name: "Charlie", role: "admin"}],
+  #   #     "user"=>[{name: "Bob", role: "user"}]}
+  #
+  # @example Group by nested keys
+  #   data = [
+  #     {department: {name: "Sales"}, employee: "Alice"},
+  #     {department: {name: "IT"}, employee: "Bob"},
+  #     {department: {name: "Sales"}, employee: "Charlie"}
+  #   ]
+  #   data.group_by_key(:department, :name)
+  #   # => {"Sales"=>[{department: {name: "Sales"}, employee: "Alice"},
+  #   #                {department: {name: "Sales"}, employee: "Charlie"}],
+  #   #     "IT"=>[{department: {name: "IT"}, employee: "Bob"}]}
+  #
+  # @example With transformation block
+  #   users.group_by_key(:role) { |role| role.upcase }
+  #   # => {"ADMIN"=>[{name: "Alice", role: "admin"}, {name: "Charlie", role: "admin"}],
+  #   #     "USER"=>[{name: "Bob", role: "user"}]}
+  #
+  def group_by_key(*keys, &block)
+    group_by do |value|
+      result = value.respond_to?(:dig) ? value.dig(*keys) : nil
+      result = yield(result) if block
+      result
+    end
+  end
 end

data/lib/everythingrb/core/hash.rb

@@ -29,6 +29,32 @@ class Hash
   #
   EMPTY_STRUCT = Struct.new(:_).new(nil)
 
+  #
+  # Creates a new Hash that automatically initializes missing keys with nested hashes
+  #
+  # This method creates a hash where any missing key access will automatically
+  # create another nested hash with the same behavior, allowing for unlimited
+  # nesting depth without explicit initialization.
+  #
+  # @return [Hash] A hash that recursively creates nested hashes for missing keys
+  #
+  # @example Basic usage with two levels
+  #   users = Hash.new_nested_hash
+  #   users[:john][:role] = "admin"  # No need to initialize users[:john] first
+  #   users # => {john: {role: "admin"}}
+  #
+  # @example Deep nesting without initialization
+  #   stats = Hash.new_nested_hash
+  #   (stats[:server][:region][:us_east][:errors] = []) << "Some Error"
+  #   stats # => {server: {region: {us_east: {errors: ["Some Error"]}}}}
+  #
+  # @note While extremely convenient, be cautious with very deep structures
+  #   as this creates new hashes on demand for any key access
+  #
+  def self.new_nested_hash
+    new { |hash, key| hash[key] = new_nested_hash }
+  end
+
   #
   # Combines filter_map and join operations
   #
@@ -54,6 +80,53 @@ class Hash
     filter_map(&block).join(join_with)
   end
 
+  #
+  # Recursively converts all values that respond to #to_h
+  #
+  # Similar to #to_h but recursively traverses the Hash structure
+  # and calls #to_h on any object that responds to it. Useful for
+  # normalizing nested data structures and parsing nested JSON.
+  #
+  # @return [Hash] A deeply converted hash with all nested objects converted
+  #
+  # @example Converting nested Data objects
+  #   user = { name: "Alice", metadata: Data.define(:source).new(source: "API") }
+  #   user.to_deep_h  # => {name: "Alice", metadata: {source: "API"}}
+  #
+  # @example Parsing nested JSON strings
+  #   nested = { profile: '{"role":"admin"}' }
+  #   nested.to_deep_h  # => {profile: {role: "admin"}}
+  #
+  # @example Mixed nested structures
+  #   data = {
+  #     config: OpenStruct.new(api_key: "secret"),
+  #     users: [
+  #       Data.define(:name).new(name: "Bob"),
+  #       {role: "admin"}
+  #     ]
+  #   }
+  #   data.to_deep_h
+  #   # => {
+  #   #      config: {api_key: "secret"},
+  #   #      users: [{name: "Bob"}, {role: "admin"}]
+  #   #    }
+  #
+  def to_deep_h
+    transform_values do |value|
+      case value
+      when Hash
+        value.to_deep_h
+      when Array
+        value.to_deep_h
+      when String
+        # If the string is not valid JSON, #to_deep_h will return `nil`
+        value.to_deep_h || value
+      else
+        value.respond_to?(:to_h) ? value.to_h : value
+      end
+    end
+  end
+
   #
   # Converts hash to an immutable Data structure
   #
@@ -143,8 +216,162 @@ class Hash
   #   { user: { name: "Alice", roles: ["admin"] } }.deep_freeze
   #   # => Hash and all nested structures are now frozen
   #
+  # @note CAUTION: Be careful when freezing collections that contain class objects
+  #   or singleton instances - this will freeze those classes/objects globally!
+  #   Only use deep_freeze on pure data structures you want to make immutable.
+  #
   def deep_freeze
     each_value { |v| v.respond_to?(:deep_freeze) ? v.deep_freeze : v.freeze }
     freeze
   end
+
+  # Allows calling original method. See below
+  alias_method :og_transform_values, :transform_values
+
+  # Allows calling original method. See below
+  alias_method :og_transform_values!, :transform_values!
+
+  #
+  # Transforms hash values while allowing access to keys via the chainable with_key method
+  #
+  # This method either performs a standard transform_values operation if a block is given,
+  # or returns an enumerator with a with_key method that passes both the key and value
+  # to the block.
+  #
+  # @yield [value] Block to transform each value (standard behavior)
+  # @yieldparam value [Object] The value to transform
+  # @yieldreturn [Object] The transformed value
+  #
+  # @return [Hash, Enumerator] Result hash or Enumerator with with_key method
+  #
+  # @example Standard transform_values
+  #   {a: 1, b: 2}.transform_values { |v| v * 2 }
+  #   # => {a: 2, b: 4}
+  #
+  # @example Using with_key to access keys during transformation
+  #   {a: 1, b: 2}.transform_values.with_key { |k, v| "#{k}_#{v}" }
+  #   # => {a: "a_1", b: "b_2"}
+  #
+  def transform_values(&block)
+    return transform_values_enumerator if block.nil?
+
+    og_transform_values(&block)
+  end
+
+  #
+  # Transforms hash values in place while allowing access to keys via the chainable with_key method
+  #
+  # This method either performs a standard transform_values! operation if a block is given,
+  # or returns an enumerator with a with_key method that passes both the key and value
+  # to the block, updating the hash in place.
+  #
+  # @yield [value] Block to transform each value (standard behavior)
+  # @yieldparam value [Object] The value to transform
+  # @yieldreturn [Object] The transformed value
+  #
+  # @return [self, Enumerator]
+  #   Original hash with transformed values or Enumerator with with_key method
+  #
+  # @example Standard transform_values!
+  #   hash = {a: 1, b: 2}
+  #   hash.transform_values! { |v| v * 2 }
+  #   # => {a: 2, b: 4}
+  #
+  # @example Using with_key to access keys during in-place transformation
+  #   hash = {a: 1, b: 2}
+  #   hash.transform_values!.with_key { |k, v| "#{k}_#{v}" }
+  #   # => {a: "a_1", b: "b_2"}
+  #
+  def transform_values!(&block)
+    return transform_values_bang_enumerator if block.nil?
+
+    og_transform_values!(&block)
+  end
+
+  #
+  # Returns the first value where the key-value pair satisfies the given condition
+  #
+  # @yield [key, value] Block that determines whether to include the value
+  # @yieldparam key [Object] The current key
+  # @yieldparam value [Object] The current value
+  # @yieldreturn [Boolean] Whether to include this value
+  #
+  # @return [Object, nil] The first matching value or nil if none found
+  # @return [Enumerator] If no block is given
+  #
+  # @example Find first admin user by role
+  #   users = {
+  #     alice: {name: "Alice", role: "admin"},
+  #     bob: {name: "Bob", role: "user"},
+  #     charlie: {name: "Charlie", role: "admin"}
+  #   }
+  #   users.value_where { |k, v| v[:role] == "admin" } # => {name: "Alice", role: "admin"}
+  #
+  def value_where(&block)
+    return to_enum(:value_where) if block.nil?
+
+    find(&block)&.last
+  end
+
+  #
+  # Returns all values where the key-value pairs satisfy the given condition
+  #
+  # @yield [key, value] Block that determines whether to include the value
+  # @yieldparam key [Object] The current key
+  # @yieldparam value [Object] The current value
+  # @yieldreturn [Boolean] Whether to include this value
+  #
+  # @return [Array] All matching values
+  # @return [Enumerator] If no block is given
+  #
+  # @example Find all admin users by role
+  #   users = {
+  #     alice: {name: "Alice", role: "admin"},
+  #     bob: {name: "Bob", role: "user"},
+  #     charlie: {name: "Charlie", role: "admin"}
+  #   }
+  #   users.values_where { |k, v| v[:role] == "admin" }
+  #   # => [{name: "Alice", role: "admin"}, {name: "Charlie", role: "admin"}]
+  #
+  def values_where(&block)
+    return to_enum(:values_where) if block.nil?
+
+    select(&block).values
+  end
+
+  private
+
+  def transform_values_enumerator
+    original_hash = self
+    enum = to_enum(:transform_values)
+
+    # Add the with_key method directly to the enum
+    enum.define_singleton_method(:with_key) do |&block|
+      raise ArgumentError, "Missing block for Hash#transform_values.with_key" if block.nil?
+
+      original_hash.each_pair.with_object({}) do |(key, value), output|
+        output[key] = block.call(key, value)
+      end
+    end
+
+    enum
+  end
+
+  def transform_values_bang_enumerator
+    original_hash = self
+    enum = to_enum(:transform_values!)
+
+    # Add the with_key method directly to the enum
+    enum.define_singleton_method(:with_key) do |&block|
+      raise ArgumentError, "Missing block for Hash#transform_values!.with_key" if block.nil?
+
+      original_hash.each_pair do |key, value|
+        original_hash[key] = block.call(key, value)
+      end
+
+      original_hash
+    end
+
+    enum
+  end
 end

data/lib/everythingrb/version.rb

@@ -7,5 +7,5 @@
 #
 module Everythingrb
   # Current version of the everythingrb gem
-  VERSION = "0.2.5"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: everythingrb
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.1
 platform: ruby
 authors:
 - Bryan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-30 00:00:00.000000000 Z
+date: 2025-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ostruct