uberloader 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18172000e1265e1e5a71cf636dc7589a9a66ea126cbf4284657b9470b4e056eb
-  data.tar.gz: 5ed598b20223993795bd34cbeb2dacbe0a972e1c901d17598240b797b3db05bc
+  metadata.gz: 8492bc8a8089cb6ece086e3b2b0f0827e8c52f59d7d26d6813153c0ea7d08193
+  data.tar.gz: a9586e3880975bcbba4975bb969c3b0be354c6d8b51059cae77aae5d84ad86b9
 SHA512:
-  metadata.gz: d217e55a50c48408823c1415a7413f62645e4384e7000ef30cc6ca2764298820e86d8cd8222738f64a4fa9a3f65fe173aca69ef2e2c06f08adfa2b1f53286a3a
-  data.tar.gz: c787e50e4d5e89cfd0673aa5f52e6634bc91d92396001f5b559b47fc0f080d271af2e6cb9ca45cca2a59632d6b7616bccaebc753b0669d52ca8583036224ce46
+  metadata.gz: d0a7b5dc7990d96df8c9075eff13283543f6e8dfc17eca55095a7a5ab7e629fdd1a0d4f31ecd68b5cc75c143bba73291e6638e410a446bd16f77e6c89aeffd92
+  data.tar.gz: 5c595cbf5702da0a6f9fdd558ab6193efc33509de2c96ac61f95da1158e8a4d811ee11dd8ab59f4c81a15868ca2d10ede18d8d62f7869a23ca66a0bc25bec3f5

data/README.md

@@ -1,6 +1,9 @@
 # Uberloader
 
-Uberloader is a new way of preloading associations in ActiveRecord. Nested preloads use blocks. Custom scopes may be given as args and/or as method calls inside a block.
+Uberloader is a new way of preloading associations in ActiveRecord. It works like `preload`, but with the following changes:
+
+* Custom scopes may be given.
+* Nested preloads use blocks.
 
 ```ruby
 widgets = Widget
@@ -14,6 +17,7 @@ widgets = Widget
     # and their subparts, using a custom scope
     u.uberload(:subparts) do
       u.scope my_subparts_scope_helper
+      u.scope Subpart.where(kind: params[:sub_kinds]) if params[:sub_kinds]&.any?
 
       u.uberload(:foo) do
         u.uberload(:bar)
@@ -22,9 +26,11 @@ widgets = Widget
   end
 ```
 
-## Status
+Install with Bundler:
 
-Uberloader is an attempt to bring [ideas from OccamsRecord](https://github.com/jhollinger/occams-record/?tab=readme-ov-file#advanced-eager-loading) deeper into ActiveRecord, making them easier to use in existing applications. It's usable in production, but **note that it monkeypatches** `ActiveRecord::Relation#preload_associations`. YMMV if other gems monkeypatch this method.
+```bash
+bundle add uberloader
+```
 
 ## Interaction with preload and includes
 
@@ -36,6 +42,14 @@ widgets = Widget
   .uberload(:parts, scope: Part.order(:name))
 ```
 
+## On Monkeypatches and Safety
+
+Regretably, none of this is possible without monkeypatching `ActiveRecord::Relation`'s non-public `preload_associations` method. While small, the patch has no guarntee of working in the next minor, or even tiny, patch.
+
+To assess its stability over time, I ran Uberloader's unit tests against the full matrix of (supported) ActiveRecord and Uberloader versions. They passed consistently, but with predictable clusters of failures around pre-release and X.0.0 versions.
+
+I will keep these tests running daily, and against this project's `main` branch as well. [You can find the link to the results here](https://github.com/jhollinger/uberloader/blob/docs/VERSION_COMPATIBILITY.md). If something breaks, I'll try to fix it. If we're lucky, maybe this behavior could get _into_ Rails itself someday...
+
 ## Testing
 
 Testing is fully scripted under the `bin/` directory. Appraisal is used to test against various ActiveRecord versions, and Docker or Podman is used to test against various Ruby versions. The combinations to test are defined in [test/matrix](https://github.com/jhollinger/uberloader/blob/main/test/matrix).
@@ -61,3 +75,18 @@ bin/test ruby-3.3 ar-7.1 sqlite3 N=test_add_preload_values
 # Use podman
 PODMAN=1 bin/testall
 ```
+
+### Version compatibility testing
+
+```bash
+# Test all combinations of (supported) ActiveRecord versions against all uberloader versions
+bin/testall-compatibility
+
+# Output the results as a Markdown table
+bin/generate-version-test-table
+
+# Run tests for specific versions
+#                      Appraisal  ActiveRecord  Uberloader
+bin/test-compatibility 7.1        7.1.3.2       0.1.0
+bin/test-compatibility 7.1        7.1.3.2       HEAD
+```

data/lib/uberloader/version.rb

@@ -1,3 +1,3 @@
 module Uberloader
-  VERSION = "0.1.0".freeze
+  VERSION = "0.2.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: uberloader
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-22 00:00:00.000000000 Z
+date: 2024-08-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -19,7 +19,7 @@ dependencies:
         version: '6.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7.2'
+        version: '7.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,7 @@ dependencies:
         version: '6.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7.2'
+        version: '7.3'
 description: Customizable SQL when preloading in ActiveRecord
 email: jordan.hollinger@gmail.com
 executables: []