wholeable 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22a0b004027d8ea27c1d2ca4ec1c9df4c86b9b3f30f568454c8d0619a778cf6d
-  data.tar.gz: c1edd95f553852b03984f9a24d205cdad50d80fa5bfdad7b5955371e7a5242cd
+  metadata.gz: 449fc75d34cc505190e11670452eed7f8a1f58d7f24f2df36fe24857f055a188
+  data.tar.gz: c958dca76cc2446384579ec537961f77da10c40680c71b10768335dead1f919e
 SHA512:
-  metadata.gz: 92b81b6a566b0bdc4021eb1cd06362c33510104177dd13c7c4d5d17edef56b1607ff539ca1005ace1e2d686d198c8a4e211c9c1d2863c283f68c377bb3425431
-  data.tar.gz: 59fa9a85e0902728ef204fb27df3044aaec1d319aaf84657e6093ade027b3a3c1954db547c0724448b9f46b67bae8cd55612a50be2ec1d4f8c451c485065ae66
+  metadata.gz: 8d551292b8f50f38f9fccfa1bae6a8e9ff174c82a76106f94dac6f748a4cff6a8bf1628d296455b8b3a61ceef0752e70ce709255195477b5f4ab57c8792620e5
+  data.tar.gz: f143f59acccf45cfd19042715d6ad3d0619a2755a28e6c7b39f2288aa0cde174454cec77c6864b8e7418c2ef662883669eb94b1cb2b1d1fda2961c9b7a370590

data/README.adoc

@@ -10,10 +10,10 @@
 
 = Wholeable
 
-Wholeable allows you to turn your object into a _whole value object_ by ensuring object equality is determined by the values of the object instead of by identity. Whole value objects -- or value objects in general -- have the following traits as noted via link:https://en.wikipedia.org/wiki/Value_object[Wikipedia]:
+Wholeable allows you to turn your object into a _whole value object_ by ensuring object equality is determined by the values of the object instead of object identity. Whole value objects -- or value objects in general -- have the following traits:
 
 * Equality is determined by the values that make up an object and not by link:https://en.wikipedia.org/wiki/Identity_(object-oriented_programming)[identity] (i.e. memory address) which is the default behavior for all {ruby_link} objects except for {data_link} and {structs_link}.
-* Identity remains unique since two objects can have the same values but different identity. This means `BasicObject#equal?` is never overwritten -- which is strongly discouraged -- as per link:https://rubyapi.org/o/basicobject#method-i-3D-3D[BasicObject] documentation.
+* Identity remains unique since two objects can have the same values but different identity. This means `BasicObject#equal?` is never overwritten -- which is strongly discouraged -- as per link:https://docs.ruby-lang.org/en/master/BasicObject.html[BasicObject] documentation.
 * Value objects should be immutable (i.e. frozen) by default. This implementation enforces a strict adherence to immutability in order to ensure value objects remain equal and discourage mutation.
 
 toc::[]
@@ -70,6 +70,8 @@ To use, include Wholeable along with a list of attributes that make up your whol
 
 [source,ruby]
 ----
+require "wholeable"
+
 class Person
   include Wholeable[:name, :email]
 
@@ -162,10 +164,12 @@ Both methods work but use `.[]` when supplying arguments and `.new` when you don
 
 === Mutability
 
-All whole value objects are frozen by default. You can change behavior by specifying whether instances should be mutable by passing `kind: :mutable` as a keyword argument. Example:
+Instances are frozen by default. You can change behavior by specifying whether instances should be mutable by passing `kind: :mutable` as a keyword argument. Example:
 
 [source,ruby]
 ----
+require "wholeable"
+
 class Person
   include Wholeable[:name, :email, kind: :mutable]
 
@@ -196,6 +200,8 @@ Unlike {data_link} or {structs_link}, you can subclass a whole value object. Exa
 
 [source,ruby]
 ----
+require "wholeable"
+
 class Person
   include Wholeable[:name]
 
@@ -229,6 +235,8 @@ If your ancestry is a mixed (immutable and mutable) then behavior is specific to
 
 [source,ruby]
 ----
+require "wholeable"
+
 class Parent
   include Wholeable[:one]
 
@@ -255,10 +263,12 @@ child.frozen?    # false
 
 Notice, when attempting to mutate the `one` attribute, you get a `NoMethodError`. This is because `#one=` is defined by the _immutable_ parent while `#two=` is defined on the _mutable_ child.
 
-If you the flip mutability of your ancestry, you can make your parent mutable while the child immutable for different behavior. Example:
+If you the flip mutability of your ancestry, you can make your parent mutable while the child is immutable with different behavior. Example:
 
 [source,ruby]
 ----
+require "wholeable"
+
 class Parent
   include Wholeable[:one, kind: :mutable]
 
@@ -296,47 +306,59 @@ Whole values can be broken via the following situations:
 
 == Performance
 
-The performance of this gem is good but definitely slower than native support for {data_link} and {structs_link} because they are written in C. To illustrate, here's a micro benchmark for comparison:
+The performance of this gem is slightly slower than native support for {data_link} and {structs_link} because they are written in C. To illustrate, here's a micro benchmark for comparison:
 
 ----
 INITIALIZATION
 
-ruby 3.3.5 (2024-09-03 revision ef084cc8f4) +YJIT [arm64-darwin23.6.0]
+ruby 4.0.1 (2026-01-13 revision e04267a14b) +YJIT +PRISM [arm64-darwin25.2.0]
 Warming up --------------------------------------
-                Data   470.027k i/100ms
-              Struct   422.010k i/100ms
-               Whole   805.945k i/100ms
+                Data   411.580k i/100ms
+           Equalizer     2.225M i/100ms
+           Equatable     2.321M i/100ms
+              Struct   455.823k i/100ms
+           Wholeable   859.120k i/100ms
 Calculating -------------------------------------
-                Data      4.750M (± 1.1%) i/s  (210.53 ns/i) -     23.971M in   5.047225s
-              Struct      4.579M (± 1.1%) i/s  (218.38 ns/i) -     23.211M in   5.069228s
-               Whole      9.408M (± 1.2%) i/s  (106.29 ns/i) -     47.551M in   5.055033s
+                Data      4.903M (± 8.8%) i/s  (203.94 ns/i) -     24.695M in   5.072786s
+           Equalizer     25.434M (± 8.5%) i/s   (39.32 ns/i) -    126.805M in   5.018058s
+           Equatable     25.399M (± 7.9%) i/s   (39.37 ns/i) -    127.656M in   5.053633s
+              Struct      4.811M (± 7.7%) i/s  (207.85 ns/i) -     24.159M in   5.048700s
+           Wholeable     10.649M (± 8.9%) i/s   (93.91 ns/i) -     53.265M in   5.044738s
 
 Comparison:
-               Whole:  9407938.7 i/s - 1.60x  slower
-                Data:  4750013.8 i/s - 3.17x  slower
-              Struct:  4579253.1 i/s - 3.28x  slower
+           Equalizer: 25434240.3 i/s
+           Equatable: 25398808.9 i/s - same-ish: difference falls within error
+           Wholeable: 10648737.2 i/s - 2.39x  slower
+                Data:  4903352.0 i/s - 5.19x  slower
+              Struct:  4811046.3 i/s - 5.29x  slower
 
-BEHAVIOR
+MESSAGING
 
-ruby 3.3.5 (2024-09-03 revision ef084cc8f4) +YJIT [arm64-darwin23.6.0]
+ruby 4.0.1 (2026-01-13 revision e04267a14b) +YJIT +PRISM [arm64-darwin25.2.0]
 Warming up --------------------------------------
-                Data   129.006k i/100ms
-              Struct   129.832k i/100ms
-           Wholeable    78.861k i/100ms
+                Data   125.714k i/100ms
+           Equalizer    97.991k i/100ms
+           Equatable    94.801k i/100ms
+              Struct   121.077k i/100ms
+           Wholeable    96.806k i/100ms
 Calculating -------------------------------------
-                Data      1.336M (± 3.6%) i/s  (748.33 ns/i) -      6.708M in   5.027517s
-              Struct      1.341M (± 1.7%) i/s  (745.89 ns/i) -      6.751M in   5.037050s
-           Wholeable    816.232k (± 1.9%) i/s    (1.23 μs/i) -      4.101M in   5.025751s
+                Data      1.368M (±12.1%) i/s  (731.11 ns/i) -      6.789M in   5.052046s
+           Equalizer    997.443k (±11.4%) i/s    (1.00 μs/i) -      4.998M in   5.074622s
+           Equatable    996.404k (± 9.6%) i/s    (1.00 μs/i) -      5.024M in   5.087767s
+              Struct      1.429M (±10.0%) i/s  (699.99 ns/i) -      7.144M in   5.051871s
+           Wholeable    967.377k (±10.7%) i/s    (1.03 μs/i) -      4.840M in   5.060414s
 
 Comparison:
-              Struct:  1340687.5 i/s
-                Data:  1336304.1 i/s - same-ish: difference falls within error
-           Wholeable:   816232.0 i/s - 1.64x  slower
+              Struct:  1428586.9 i/s
+                Data:  1367792.5 i/s - same-ish: difference falls within error
+           Equalizer:   997443.1 i/s - 1.43x  slower
+           Equatable:   996404.3 i/s - 1.43x  slower
+           Wholeable:   967377.2 i/s - 1.48x  slower
 ----
 
-While the above isn't bad, you can definitely see this gem is slower than Ruby's own native objects when interacting with it despite being faster upon initialization.
+While the above isn't bad, you can see this gem is slower than Ruby's own native objects during interaction despite being faster upon initialization.
 
-Default to using {data_link} or {structs_link} but, if you find yourself needing a whole value object with more behavior than what a `Data` or `Struct` can provide, then this gem is a good solution.
+Prefer using {data_link} or {structs_link} first but, if you find yourself needing a whole value object with more behavior than what a `Data` or `Struct` can provide, then this gem is a good solution.
 
 == Development
 

data/wholeable.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "wholeable"
-  spec.version = "2.0.0"
+  spec.version = "2.2.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/wholeable"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wholeable
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -9,9 +9,9 @@ bindir: bin
 cert_chain:
 - |
   -----BEGIN CERTIFICATE-----
-  MIIENjCCAp6gAwIBAgIBAjANBgkqhkiG9w0BAQsFADBBMQ8wDQYDVQQDDAZicm9v
+  MIIENjCCAp6gAwIBAgIBAzANBgkqhkiG9w0BAQsFADBBMQ8wDQYDVQQDDAZicm9v
   a2UxGjAYBgoJkiaJk/IsZAEZFgphbGNoZW1pc3RzMRIwEAYKCZImiZPyLGQBGRYC
-  aW8wHhcNMjUwMzIyMTQ1NDE3WhcNMjYwMzIyMTQ1NDE3WjBBMQ8wDQYDVQQDDAZi
+  aW8wHhcNMjYwMzI1MTI0OTEyWhcNMjcwMzI1MTI0OTEyWjBBMQ8wDQYDVQQDDAZi
   cm9va2UxGjAYBgoJkiaJk/IsZAEZFgphbGNoZW1pc3RzMRIwEAYKCZImiZPyLGQB
   GRYCaW8wggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQCro8tj5/E1Hg88
   f4qfiwPVd2zJQHvdYt4GHVvuHRRgx4HGhJuNp+4BId08RBn7V6V1MW6MY3kezRBs
@@ -23,15 +23,15 @@ cert_chain:
   GUHU9MyIXbFOsnp3K3ADrAVjPWop8EZkmUR3MV/CUm00w2cZHCSGiXl1KMpiVKvk
   Ywr1gd2ZME4QLSo+EXUtLxDUa/W3xnBS8dBOuMMz02FPWYr3PN8CAwEAAaM5MDcw
   CQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0OBBYEFAFgmv0tYMZnItuPycSM
-  F5wykJEVMA0GCSqGSIb3DQEBCwUAA4IBgQBlzRfyAYx/fCFjizS0Npxw4+4T3aYL
-  hbXoDqQRWjxuhFZcXUymhz3r8/Ltyri9lSof8grzB+8/+mrMVms7Gwt5qolk6zdn
-  FkySGy/jmpN12ldOHFbBEnyVBZNBvOBVb8zkkw8PhiHdBdXOUm4Jy39yJvBLfjcC
-  iM1aeWPmgPy1GbvZU+leRGZLt6dRIR9oCDXcWLRjha8xLMoz6Yn9fJBYexBA3iEz
-  h5S7pn4AX/JhVRiSyl8pAy4jEKydpyQrliH3gHkpNmUS/XDczP+9xX1bAB4BvqL2
-  NCxMcQ+hiJNqCKpPgHxaOOHZfIxV33logIuPEQ8NryHAwZ9ZWnwtYDE8kQGGKskI
-  Kkm6QT474hZl7MpwiJjWgW313CR7jUEekQahX1QxCxHPI7LSrKpno0plH3uWIOQp
-  KUlkb9uyACBgyRO52ZHiDVI8YvtU5O/j9pSes9/3XgvBeC1onx4qWp+uRX7eVsYS
-  GiijocTc3enZVrXERetaXj8/9XWs3fB3HWY=
+  F5wykJEVMA0GCSqGSIb3DQEBCwUAA4IBgQAG+ykjp+DIXSybGEtX+/ve974mYfN6
+  8U7qcVfRM+qDSOZ+97iu30qUTbVAKIHlHCDKRn3SgOffDUB5VU2MsJBh/3TPKWBZ
+  anB/uzMcwOfru+qyA3b7ZFqZzRLWmR5FtPObFxc0gYMT3YvLNHk2Nb9Vjq/PoiGG
+  e75PXweDOokwDA5m1gMOz1rdp/dlGMXkSFQg94PPVyUKXgO4VzWTgePSDxOIL+v6
+  +OWV6AaEH9BaqxnmdA5ubi0L7bhl0gbN92FxpNO3kpTjww8kme856a+wCK3qyM5w
+  7ZLbUexynDN0Au8eSpT2Bf6ztGmB1S9ffzDJsGX1/lkpMIB51e48Xe2+gzzOgemk
+  CdZaGupj6WkarnT8kh/cPtyA5ax4rGX6GOS8meGxzkv8Uy0JSEOYAp6wLfIisYZp
+  IJBIXIOkwKKJ0eB5YHrUSJxzpP4LlcIg/eTftaXmJdYjy+2VRrCZYDjfguyLmMjR
+  KR9w4/Fjvqy87kCHmxMWa6IL2Vzt1Clm2cA=
   -----END CERTIFICATE-----
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
@@ -73,7 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Provides whole value object behavior.
 test_files: []