API: added short-cut methods for related records

For example, `authors` association provides the following extras:
* `.authored_by` scope to filter records by authors,
* `#authored_by?` — to check if the record is authored by provided ones,
* `#authored_by!` — to add an author.

NOTE: this applies to role-based associations with actor-like models
only.

Author: Alexander-Senko

CHANGELOG.md

@@ -12,6 +12,11 @@
 
 - `referencing`/`referenced_by` scopes to filter by related records.
 - `#referencing!`/`#referenced_by!` setters to add related records.
+- Short-cut methods for related records.
+	For example, `authors` association provides the following extras:
+	- `.authored_by` scope to filter records by authors,
+	- `#authored_by?` — to check if the record is authored by provided ones,
+	- `#authored_by!` — to add an author.
 
 
 ## [0.10.0] — 2025-04-23

lib/adjustable_schema/active_record/association.rb

@@ -15,14 +15,16 @@ class Association < Struct.new( # :nodoc:
 			require_relative 'association/scopes'
 			require_relative 'association/roleless'
 			require_relative 'association/hierarchy'
+			require_relative 'association/referenced'
 
 			include Memery
 
 			def initialize(...)
 				super
 
-				extend Roleless  if roleless?
-				extend Hierarchy if hierarchy?
+				extend Roleless   if roleless?
+				extend Hierarchy  if hierarchy?
+				extend Referenced if source? and role and target.actor?
 			end
 
 			def define
@@ -58,13 +60,15 @@ def define_relationships
 
 			def define_scopes
 				scopes
-						.reject { owner.singleton_class.method_defined? _1 }
+						.reject { owner.respond_to? _1 }
 						.each   { owner.scope _1, _2 }
 			end
 
 			def define_methods
-				flags
-						.transform_keys { :"#{it}?" }
+				{
+						**flag_methods,
+						**setter_methods,
+				}
 						.reject { owner.method_defined? _1 }
 						.each   { owner.define_method _1, &_2 }
 			end
@@ -93,6 +97,14 @@ def flags
 				}
 			end
 
+			def flag_methods = flags
+					.transform_keys { :"#{it}?" }
+
+			def setters = {}
+
+			def setter_methods = setters
+					.transform_keys { :"#{it}!" }
+
 			memoize def options = {
 					through:     define_relationships,
 					source:      direction,

lib/adjustable_schema/active_record/association/referenced.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module AdjustableSchema
+	module ActiveRecord
+		module Association::Referenced # :nodoc:
+			private
+
+			def scopes
+				role = self.role.name # save the context
+
+				{
+						**super,
+
+						referenced_name => -> { referenced_by it, role: },
+				}
+			end
+
+			def flags
+				name = self.name # save the context
+
+				{
+						**super,
+
+						referenced_name => -> { it.in? send name },
+				}
+			end
+
+			def setters
+				role = self.role.name # save the context
+
+				{
+						**super,
+
+						referenced_name => -> { referenced_by! it, role: },
+				}
+			end
+
+			using Association::Inflections
+
+			def referenced_name = :"#{object_name.passivize}_by"
+		end
+	end
+end

test/lib/active_record/association_test.rb

@@ -76,17 +76,29 @@ def defines_methods(&)
 				let(:association_name) { 'authors' }
 				let(:name_for_any)     { 'authored' }
 
-				defines_scopes
-				defines_methods
+				defines_scopes do
+					_(owner).must_respond_to :authored_by
+				end
+
+				defines_methods do
+					_(record).must_respond_to :authored_by?
+					_(record).must_respond_to :authored_by!
+				end
 
 				describe 'without a role' do
 					let(:role) {}
 
 					let(:association_name) { 'users' }
 					let(:name_for_any)     { 'used' }
 
-					defines_scopes
-					defines_methods
+					defines_scopes do
+						_(owner).wont_respond_to :used_by
+					end
+
+					defines_methods do
+						_(record).wont_respond_to :used_by?
+						_(record).wont_respond_to :used_by!
+					end
 				end
 			end