everythingrb 0.6.1 → 0.8.0

data/lib/everythingrb/array.rb

@@ -6,7 +6,6 @@
 # Provides:
 # - #join_map: Combine filter_map and join operations in one step
 # - #key_map, #dig_map: Extract values from arrays of hashes
-# - #deep_freeze: Recursively freeze array and contents
 # - #compact_prefix, #compact_suffix, #trim_nils: Clean up array boundaries
 # - ActiveSupport integrations: #trim_blanks and more when ActiveSupport is loaded
 #
@@ -16,6 +15,8 @@
 #   [{name: "Alice"}, {name: "Bob"}].key_map(:name)  # => ["Alice", "Bob"]
 #
 class Array
+  include Everythingrb::InspectQuotable
+
   #
   # Combines filter_map and join operations
   #
@@ -73,34 +74,17 @@ class Array
   # @return [Array] Array of nested values
   #
   # @example
-  #   [
+  #   users = [
   #     {user: {profile: {name: "Alice"}}},
   #     {user: {profile: {name: "Bob"}}}
-  #   ].dig_map(:user, :profile, :name)
+  #   ]
+  #   users.dig_map(:user, :profile, :name)
   #   # => ["Alice", "Bob"]
   #
   def dig_map(*keys)
     map { |v| v.dig(*keys) }
   end
 
-  #
-  # Recursively freezes self and all of its contents
-  #
-  # @return [self] Returns the frozen array
-  #
-  # @example Freeze an array with nested structures
-  #   ["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
-  end
-
   #
   # Removes nil values from the beginning of an array
   #

data/lib/everythingrb/boolean.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+#
+# Extensions to Ruby's core TrueClass
+#
+# Provides:
+# - #in_quotes, #with_quotes: Wrap boolean values in quotes
+#
+# @example
+#   require "everythingrb/boolean"
+#
+#   true.in_quotes   # => "\"true\""
+#   false.in_quotes  # => "\"false\""
+#
+class TrueClass
+  include Everythingrb::InspectQuotable
+end
+
+#
+# Extensions to Ruby's core FalseClass
+#
+# Provides:
+# - #in_quotes, #with_quotes: Wrap boolean values in quotes
+#
+# @example
+#   require "everythingrb/boolean"
+#
+#   true.in_quotes   # => "\"true\""
+#   false.in_quotes  # => "\"false\""
+#
+class FalseClass
+  include Everythingrb::InspectQuotable
+end

data/lib/everythingrb/data.rb

@@ -5,11 +5,18 @@
 #
 # Provides:
 # - #to_deep_h: Recursively convert to hash with all nested objects
+# - #in_quotes, #with_quotes: Wrap object in quotes
 #
 class Data
+  include Everythingrb::InspectQuotable
+
   #
   # Recursively converts the Data object and all nested objects to hashes
   #
+  # This method traverses the entire Data structure, converting not just
+  # the top-level Data object but also nested Data objects, Structs, OpenStructs,
+  # and any other objects that implement `to_h`.
+  #
   # @return [Hash] A deeply converted hash of the Data object
   #
   # @example

data/lib/everythingrb/date.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+#
+# Extensions to Ruby's core Date class
+#
+# Provides:
+# - #in_quotes, #with_quotes: Wrap date representations in quotes
+#
+# @example
+#   require "everythingrb/date"
+#
+#   Date.today.in_quotes
+#
+class Date
+  include Everythingrb::StringQuotable
+end
+
+#
+# Extensions to Ruby's core DateTime class
+#
+# Provides:
+# - #in_quotes, #with_quotes: Wrap time representations in quotes
+#
+# @example
+#   require "everythingrb/date"
+#
+#   DateTime.now.in_quotes
+#
+class DateTime < Date
+  include Everythingrb::StringQuotable
+end

data/lib/everythingrb/enumerable.rb

@@ -4,8 +4,8 @@
 # Extensions to Ruby's core Enumerable module
 #
 # Provides:
-# - #join_map: Combine filter_map and join operations
-# - #group_by_key: Group elements by a given key or nested keys
+# - #join_map: Combine filter_map and join operations into one step
+# - #group_by_key: Group elements by key or nested keys, simplifying collection organization
 #
 # @example
 #   require "everythingrb/enumerable"
@@ -24,6 +24,7 @@ module Enumerable
   # @yieldparam index [Integer] The index of the current element (only if with_index: true)
   #
   # @return [String] Joined string of filtered and transformed elements
+  # @return [Enumerator] If no block is given
   #
   # @example Without index
   #   [1, 2, nil, 3].join_map(" ") { |n| n&.to_s if n&.odd? }
@@ -57,6 +58,7 @@ module Enumerable
   # @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
+  # @return [Enumerator] If no block is given
   #
   # @example Group by a single key
   #   users = [

data/lib/everythingrb/extensions/quotable.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+#
+# Extensions for making objects quotable with double quotes
+#
+# These modules add the ability to quote objects by wrapping
+# their string representations in double quotes. This is useful for
+# generating error messages, debug output, or formatted logs where
+# you want to clearly distinguish between different value types.
+#
+# @example Basic usage with different types
+#   1.in_quotes                   # => "\"1\""
+#   nil.in_quotes                 # => "\"nil\""
+#   "hello".in_quotes             # => "\"\\\"hello\\\"\""
+#   [1, 2, 3].in_quotes           # => "\"[1, 2, 3]\""
+#
+# @example Using with collections
+#   values = [1, nil, "hello"]
+#   values.map(&:in_quotes)       # => ["\"1\"", "\"nil\"", "\"\\\"hello\\\"\""]
+#
+# @example Error messages
+#   expected = 42
+#   actual = nil
+#   raise "Expected #{expected.in_quotes} but got #{actual.in_quotes}"
+#   # => "Expected \"42\" but got \"nil\""
+#
+module Everythingrb
+  #
+  # Adds quotable functionality using inspect representation
+  #
+  # Provides methods for wrapping an object's inspection
+  # representation in double quotes.
+  #
+  # @example
+  #   [1, 2, 3].in_quotes  # => "\"[1, 2, 3]\""
+  #
+  module InspectQuotable
+    #
+    # Adds quotable functionality using inspect representation
+    #
+    # Provides methods for wrapping an object's inspection
+    # representation in double quotes.
+    #
+    # @return [String] The object's inspect representation surrounded by double quotes
+    #
+    # @example
+    #   [1, 2, 3].in_quotes      # => "\"[1, 2, 3]\""
+    #   {a: 1}.in_quotes         # => "\"{:a=>1}\""
+    #
+    def in_quotes
+      %("#{inspect}")
+    end
+
+    alias_method :with_quotes, :in_quotes
+  end
+
+  #
+  # Adds quotable functionality using to_s representation
+  #
+  # Provides methods for wrapping an object's string
+  # representation in double quotes.
+  #
+  # @example
+  #   Time.now.in_quotes  # => "\"2025-05-03 12:34:56 -0400\""
+  #
+  module StringQuotable
+    #
+    # Returns the object's string representation wrapped in double quotes
+    #
+    # @return [String] The object's to_s representation surrounded by double quotes
+    #
+    # @example
+    #   Date.today.in_quotes      # => "\"2025-05-03\""
+    #   Time.now.in_quotes        # => "\"2025-05-03 12:34:56 -0400\""
+    #
+    def in_quotes
+      %("#{self}")
+    end
+
+    alias_method :with_quotes, :in_quotes
+  end
+end

data/lib/everythingrb/extensions.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+Dir[File.expand_path("./extensions/**/*.rb", __dir__)].each { |path| require path }

data/lib/everythingrb/hash.rb

@@ -6,12 +6,14 @@
 # Provides:
 # - #to_struct, #to_ostruct, #to_istruct: Convert hashes to different structures
 # - #join_map: Combine filter_map and join operations
-# - #deep_freeze: Recursively freeze hash and contents
 # - #transform_values.with_key: Transform values with access to keys
 # - #transform, #transform!: Transform keys and values
 # - #value_where, #values_where: Find values based on conditions
 # - #rename_key, #rename_keys: Rename hash keys while preserving order
 # - ::new_nested_hash: Create automatically nesting hashes
+# - #merge_if, #merge_if!: Conditionally merge based on key-value pairs
+# - #merge_if_values, #merge_if_values!: Conditionally merge based on values
+# - #merge_compact, #merge_compact!: Merge only non-nil values
 #
 # @example
 #   require "everythingrb/hash"
@@ -19,6 +21,8 @@
 #   config.server.port  # => 443
 #
 class Hash
+  include Everythingrb::InspectQuotable
+
   #
   # A minimal empty struct for Ruby 3.2+ compatibility
   #
@@ -46,6 +50,10 @@ class Hash
   #
   # @return [Hash] A hash that creates nested hashes for missing keys
   #
+  # @note This implementation is not thread-safe for concurrent modifications of deeply
+  #   nested structures. If you need thread safety, consider using a mutex when modifying
+  #   the deeper levels of the hash.
+  #
   # @example Unlimited nesting (default behavior)
   #   users = Hash.new_nested_hash
   #   users[:john][:role] = "admin"  # No need to initialize users[:john] first
@@ -113,7 +121,7 @@ class Hash
   # 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
+  # @return [Hash] A deeply converted hash with all nested objects
   #
   # @example Converting nested Data objects
   #   user = { name: "Alice", metadata: Data.define(:source).new(source: "API") }
@@ -233,28 +241,10 @@ class Hash
     OpenStruct.new(**transform_values { |value| recurse.call(value) })
   end
 
-  #
-  # Recursively freezes self and all of its values
-  #
-  # @return [self] Returns the frozen hash
-  #
-  # @example
-  #   { 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
+  # @!visibility private
   alias_method :og_transform_values, :transform_values
 
-  # Allows calling original method. See below
+  # @!visibility private
   alias_method :og_transform_values!, :transform_values!
 
   #
@@ -333,10 +323,10 @@ class Hash
 
   # ActiveSupport integrations
   if defined?(ActiveSupport)
-    # Allows calling original method. See below
+    # @!visibility private
     alias_method :og_deep_transform_values, :deep_transform_values
 
-    # Allows calling original method. See below
+    # @!visibility private
     alias_method :og_deep_transform_values!, :deep_transform_values!
 
     #
@@ -663,4 +653,237 @@ class Hash
     self[new_key] = delete(old_key)
     self
   end
+
+  #
+  # Selects hash entries based only on their values
+  #
+  # @yield [value] Block that determines whether to include the entry
+  # @yieldparam value [Object] The current value
+  # @yieldreturn [Boolean] Whether to include this entry
+  #
+  # @return [Hash] A new hash including only entries where the block returned truthy
+  # @return [Enumerator] If no block is given
+  #
+  # @example Filter to include only present values (with ActiveSupport)
+  #   {name: "Alice", bio: nil, role: ""}.select_values(&:present?)
+  #   # => {name: "Alice"}
+  #
+  # @example Filter using more complex logic
+  #   {id: 1, count: 0, items: [1, 2, 3]}.select_values { |v| v.is_a?(Array) || v > 0 }
+  #   # => {id: 1, items: [1, 2, 3]}
+  #
+  def select_values(&block)
+    return to_enum(:select_values) if block.nil?
+
+    select { |_k, v| block.call(v) }
+  end
+
+  alias_method :filter_values, :select_values
+
+  #
+  # Selects hash entries based only on their values, modifying the hash in place
+  #
+  # @yield [value] Block that determines whether to keep the entry
+  # @yieldparam value [Object] The current value
+  # @yieldreturn [Boolean] Whether to keep this entry
+  #
+  # @return [self, nil] The modified hash, or nil if no changes were made
+  # @return [Enumerator] If no block is given
+  #
+  # @example Remove entries with empty values (with ActiveSupport)
+  #   hash = {name: "Alice", bio: nil, role: ""}
+  #   hash.select_values!(&:present?)
+  #   # => {name: "Alice"}
+  #   # hash is now {name: "Alice"}
+  #
+  def select_values!(&block)
+    return to_enum(:select_values!) if block.nil?
+
+    select! { |_k, v| block.call(v) }
+  end
+
+  alias_method :filter_values!, :select_values!
+
+  #
+  # Rejects hash entries based only on their values
+  #
+  # @yield [value] Block that determines whether to exclude the entry
+  # @yieldparam value [Object] The current value
+  # @yieldreturn [Boolean] Whether to exclude this entry
+  #
+  # @return [Hash] A new hash excluding entries where the block returned truthy
+  # @return [Enumerator] If no block is given
+  #
+  # @example Remove blank values (with ActiveSupport)
+  #   {name: "Alice", bio: nil, role: ""}.reject_values(&:blank?)
+  #   # => {name: "Alice"}
+  #
+  # @example Remove specific types of values
+  #   {id: 1, count: 0, items: [1, 2, 3]}.reject_values { |v| v.is_a?(Integer) && v == 0 }
+  #   # => {id: 1, items: [1, 2, 3]}
+  #
+  def reject_values(&block)
+    return to_enum(:reject_values) if block.nil?
+
+    reject { |_k, v| block.call(v) }
+  end
+
+  #
+  # Rejects hash entries based only on their values, modifying the hash in place
+  #
+  # @yield [value] Block that determines whether to remove the entry
+  # @yieldparam value [Object] The current value
+  # @yieldreturn [Boolean] Whether to remove this entry
+  #
+  # @return [self, nil] The modified hash, or nil if no changes were made
+  # @return [Enumerator] If no block is given
+  #
+  # @example Remove blank values in place (with ActiveSupport)
+  #   hash = {name: "Alice", bio: nil, role: ""}
+  #   hash.reject_values!(&:blank?)
+  #   # => {name: "Alice"}
+  #   # hash is now {name: "Alice"}
+  #
+  def reject_values!(&block)
+    return to_enum(:reject_values!) if block.nil?
+
+    reject! { |_k, v| block.call(v) }
+  end
+
+  #
+  # Conditionally merges key-value pairs from another hash based on a block
+  #
+  # @param other [Hash] The hash to merge from
+  #
+  # @yield [key, value] Block that determines whether to include each key-value pair
+  # @yieldparam key [Object] The key from the other hash
+  # @yieldparam value [Object] The value from the other hash
+  # @yieldreturn [Boolean] Whether to include this key-value pair
+  #
+  # @return [Hash] A new hash with conditionally merged key-value pairs
+  #
+  # @example Merge only even-numbered keys
+  #   {a: 1, b: 2}.merge_if(c: 3, d: 4) { |key, _| key.to_s.ord.even? }
+  #   # => {a: 1, b: 2, d: 4}
+  #
+  # @example Merge only positive values
+  #   {a: 1, b: 2}.merge_if(c: 3, d: -4) { |_, value| value > 0 }
+  #   # => {a: 1, b: 2, c: 3}
+  #
+  def merge_if(other = {}, &block)
+    other = other.select(&block) unless block.nil?
+
+    merge(other)
+  end
+
+  #
+  # Conditionally merges key-value pairs from another hash in place
+  #
+  # @param other [Hash] The hash to merge from
+  #
+  # @yield [key, value] Block that determines whether to include each key-value pair
+  # @yieldparam key [Object] The key from the other hash
+  # @yieldparam value [Object] The value from the other hash
+  # @yieldreturn [Boolean] Whether to include this key-value pair
+  #
+  # @return [self] The modified hash
+  #
+  # @example Merge only even-numbered keys in place
+  #   hash = {a: 1, b: 2}
+  #   hash.merge_if!(c: 3, d: 4) { |key, _| key.to_s.ord.even? }
+  #   # => {a: 1, b: 2, d: 4}
+  #
+  def merge_if!(other = {}, &block)
+    other = other.select(&block) unless block.nil?
+
+    merge!(other)
+  end
+
+  #
+  # Conditionally merges key-value pairs based only on values
+  #
+  # @param other [Hash] The hash to merge from
+  #
+  # @yield [value] Block that determines whether to include each value
+  # @yieldparam value [Object] The value from the other hash
+  # @yieldreturn [Boolean] Whether to include this value
+  #
+  # @return [Hash] A new hash with conditionally merged values
+  #
+  # @example Merge only string values
+  #   {a: 1, b: "old"}.merge_if_values(c: "new", d: 2) { |v| v.is_a?(String) }
+  #   # => {a: 1, b: "old", c: "new"}
+  #
+  def merge_if_values(other = {}, &block)
+    merge_if(other) { |k, v| block.call(v) }
+  end
+
+  #
+  # Conditionally merges key-value pairs based only on values, in place
+  #
+  # @param other [Hash] The hash to merge from
+  #
+  # @yield [value] Block that determines whether to include each value
+  # @yieldparam value [Object] The value from the other hash
+  # @yieldreturn [Boolean] Whether to include this value
+  #
+  # @return [self] The modified hash
+  #
+  # @example Merge only numeric values in place
+  #   hash = {a: 1, b: "text"}
+  #   hash.merge_if_values!(c: "ignore", d: 2) { |v| v.is_a?(Numeric) }
+  #   # => {a: 1, b: "text", d: 2}
+  #
+  def merge_if_values!(other = {}, &block)
+    merge_if!(other) { |k, v| block.call(v) }
+  end
+
+  #
+  # Merges only non-nil values from another hash
+  #
+  # This is a convenience method for the common pattern of merging
+  # only values that are not nil.
+  #
+  # @param other [Hash] The hash to merge from
+  #
+  # @return [Hash] A new hash with non-nil values merged
+  #
+  # @example Merge only non-nil values (common when building parameters)
+  #   user_id = 42
+  #   email = nil
+  #   name = "Alice"
+  #
+  #   {}.merge_compact(
+  #     id: user_id,
+  #     email: email,
+  #     name: name
+  #   )
+  #   # => {id: 42, name: "Alice"}
+  #
+  def merge_compact(other = {})
+    merge_if_values(other, &:itself)
+  end
+
+  #
+  # Merges only non-nil values from another hash, in place
+  #
+  # This is a convenience method for the common pattern of merging
+  # only values that are not nil.
+  #
+  # @param other [Hash] The hash to merge from
+  #
+  # @return [self] The modified hash
+  #
+  # @example Merge only non-nil values in place
+  #   params = {format: "json"}
+  #   params.merge_compact!(
+  #     page: 1,
+  #     per_page: nil,
+  #     sort: "created_at"
+  #   )
+  #   # => {format: "json", page: 1, sort: "created_at"}
+  #
+  def merge_compact!(other = {})
+    merge_if_values!(other, &:itself)
+  end
 end

data/lib/everythingrb/kernel.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+#
+# Extensions to Ruby's core Kernel module
+#
+# Provides:
+# - #morph: A more intuitive alias for Kernel#then (yield_self)
+#
+# @example
+#   require "everythingrb/kernel"
+#
+#   # Instead of:
+#   config.fetch(:key).then { |v| process(v) }
+#
+#   # More expressive with morph:
+#   config.fetch(:key).morph { |v| process(v) }
+#
+module Kernel
+  #
+  # Transforms the receiver by passing it to the given block and returning the block's result
+  #
+  # This method is an alias for `then` (and `yield_self`) that more clearly communicates
+  # the transformation intent.
+  #
+  # @yield [receiver] Block that transforms the receiver
+  # @yieldparam receiver [Object] The receiver object
+  # @yieldreturn [Object] The transformed result
+  #
+  # @return [Object] The result of the block
+  #
+  # @example Convert a semantic version to a string
+  #   version.to_sem_version.morph { |v| "#{v.major}.#{v.minor}" }
+  #
+  alias_method :morph, :then
+end

data/lib/everythingrb/nil.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+#
+# Extensions to Ruby's NilClass
+#
+# Provides:
+# - #in_quotes, #with_quotes: Wrap nil's string representation in quotes
+#
+# @example
+#   require "everythingrb/nil"
+#   nil.in_quotes  # => "\"nil\""
+#
+class NilClass
+  include Everythingrb::InspectQuotable
+end

data/lib/everythingrb/numeric.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+#
+# Extensions to Ruby's core Numeric class and subclasses
+#
+# Provides:
+# - #in_quotes, #with_quotes: Wrap numeric values in quotes
+#
+# @example
+#   require "everythingrb/numeric"
+#
+#   42.in_quotes      # => "\"42\""
+#   3.14.in_quotes    # => "\"3.14\""
+#   (1+2i).in_quotes  # => "\"1+2i\""
+#
+class Numeric
+  include Everythingrb::InspectQuotable
+end

data/lib/everythingrb/ostruct.rb

@@ -8,6 +8,7 @@
 # - #join_map: Combine filter_map and join operations
 # - #blank?, #present?: ActiveSupport integrations when available
 # - #to_deep_h: Recursively convert to hash with all nested objects
+# - #in_quotes, #with_quotes: Wrap struct in quotes
 #
 # @example
 #   require "everythingrb/ostruct"
@@ -16,6 +17,8 @@
 #   person.map { |k, v| "#{k}: #{v}" }  # => ["name: Alice", "age: 30"]
 #
 class OpenStruct
+  include Everythingrb::InspectQuotable
+
   # ActiveSupport integrations
   if defined?(ActiveSupport)
     #
@@ -23,6 +26,8 @@ class OpenStruct
     #
     # @return [Boolean] true if the OpenStruct has no attributes
     #
+    # @note Only available when ActiveSupport is loaded
+    #
     def blank?
       @table.blank?
     end
@@ -30,7 +35,9 @@ class OpenStruct
     #
     # Checks if the OpenStruct has any attributes
     #
-    # @return [Boolean] true if the OpenStruct has attributes
+    # @return [Boolean] true if the OpenStruct has any attributes
+    #
+    # @note Only available when ActiveSupport is loaded
     #
     def present?
       @table.present?
@@ -114,6 +121,9 @@ class OpenStruct
   #
   # Recursively converts the OpenStruct and all nested objects to hashes
   #
+  # This method will convert the OpenStruct and all nested OpenStructs,
+  # Structs, Data objects, and other convertible objects to plain hashes.
+  #
   # @return [Hash] A deeply converted hash of the OpenStruct
   #
   # @example