adjustable_schema 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b1390e4f564f54d0e8a840fae882bf7a494b51323846ab06e05a786c332fc37
-  data.tar.gz: 5458b1a98b4b3a3dea0c3a8e2cd66e42003683cbbd4af95c939af8fe1810ce34
+  metadata.gz: 5514bed45ea4246eb3af8f2331cbc0d911aa3582fadd0cf6fb3ec6fbb61f9c00
+  data.tar.gz: e042af98603878baa75b1f2a922157dd764572f568d3a836b73c509e654dd2d3
 SHA512:
-  metadata.gz: dee15ab2468fca2b6bf3739df1b65508dd80ae87830833d27895e05a21c59392e3856ffbd78742cc0c067bfd1db66b364a880f0bf5401a3a3cc5cac2879ec59e
-  data.tar.gz: 984449dfcba1f1797830b5153439d2873187b0fe32aaefe23cb21bab76b49f49906f70dc562eacb92653a531eb828c262449bf41a71b4507782de25ac38214d0
+  metadata.gz: e5d3a6f67b13c183c2728582df56f03337362b087e8486130758cdaacd87c72215dd74099a98be202d185b7a84c044d892469122f6850fadc81de6c3e98036a4
+  data.tar.gz: 2e7113dd0df58bb104086316d4c883e3fe96c2e1eb3b96bb201567937a799edd16502c303fd05a091a83d8afb6e3481a4157a7d2402fc596a80abb01fe493866

data/CHANGELOG.md

@@ -1,3 +1,36 @@
+## [0.11.0] — 2025-05-09
+
+### Changed
+
+- Deprecated `Relationship.seed!` in favor of `AdjustableSchema.relationship!`.
+- Special naming rules for “actor-like” models:
+	switched from `<associat>ful` form to check for related records’ presence back to a passive one (`<associat>ed`).
+	Thus, it’s `authored` and `edited` now instead of `authorful` and `editful`.
+- `Relationship.to`/`.of` handle STI classes precisely instead of falling back to a base class.
+- Customized inspections for `Relationship`.
+
+### Added
+
+- `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
+
+### Changed
+
+- No more polymorphic STI associations tricks (see 0dd30220 for details).
+
+### Added
+
+- Special naming rules for “actor-like” models.
+
+
 ## [0.9.0] — 2025-03-10
 
 ### Changed

data/README.md

@@ -24,7 +24,7 @@ AdjustableSchema::Relationship.create! source_type: 'Person',
 Or use a helper method:
 
 ``` ruby
-AdjustableSchema::Relationship.seed! Person => Book
+AdjustableSchema.relationship! Person => Book
 ```
 
 Now you have:
@@ -39,7 +39,7 @@ book.people
 You can create multiple role-based associations between two models.
 
 ``` ruby
-AdjustableSchema::Relationship.seed! Person => Book, roles: %w[author editor]
+AdjustableSchema.relationship! Person => Book, roles: %w[author editor]
 ```
 
 You will get:
@@ -56,12 +56,12 @@ book.editor_people
 
 #### Special cases
 
-##### "Actor-like" models
+##### “Actor-like” models
 
 In case you have set up relationships with `User` model you'll get a slightly different naming:
 
 ``` ruby
-AdjustableSchema::Relationship.seed! User => Book, roles: %w[author editor]
+AdjustableSchema.relationship! User => Book, roles: %w[author editor]
 ```
 
 ``` ruby
@@ -73,12 +73,21 @@ book.editors
 The list of models to be handled this way can be set with `actor_model_names` configuration parameter.
 It includes `User` by default.
 
+``` ruby
+AdjustableSchema::Engine.configure do
+  config.actor_model_names << 'Person'
+end
+```
+
+> [!CAUTION]
+> Names are passed instead of model classes not to mess the loading up.
+
 ##### Self-referencing models
 
 You may want to set up recursive relationships:
 
 ``` ruby
-AdjustableSchema::Relationship.seed! Person, roles: %w[friend]
+AdjustableSchema.relationship! Person, roles: %w[friend]
 ```
 
 In this case you'll get these associations:

data/app/models/adjustable_schema/relationship.rb

@@ -38,9 +38,9 @@ module AdjustableSchema
 				case object
 				when ::ActiveRecord::Base, nil
 					where association => object
-				when Class
-					where "#{association}_type" => object.ancestors
-							.grep(..object.base_class)
+				when ...::ActiveRecord::Base
+					where "#{association}_type" => object.descendants
+							.including(object)
 							.map(&:name)
 				when ::ActiveRecord::Relation
 					send(method, object.klass)
@@ -99,27 +99,13 @@ module AdjustableSchema
 						.reduce &:or
 			end
 
-			def seed! *models, roles: [], **mapping # rubocop:disable Metrics
-				return seed!({ **Hash[*models], **mapping }, roles:) if mapping.any? # support keyword arguments syntax
-
-				case models
-				in [
-						String | Symbol | Class => source_type,
-						String | Symbol | Class => target_type,
-				]
-					roles
-							.map { |name| Role.find_or_create_by! name: }
-							.then { it.presence or [ nil ] } # no roles => nameless relationship
-							.map { |role| create! source_type:, target_type:, role: }
-				in [ Hash => models ]
-					for sources, targets in models do
-						for source, target in Array(sources).product Array(targets) do
-							seed! source, target, roles:
-						end
-					end
-				in [ Class => source ]
-					seed! source, source, roles: # recursive
-				end
+			def seed!(...)
+				AdjustableSchema.deprecator.warn <<~TEXT.squish
+					#{self}.#{__method__} is deprecated and will be removed in v0.12.
+					Please use AdjustableSchema.relationship! instead.
+				TEXT
+
+				AdjustableSchema.relationship!(...)
 			end
 		end
 
@@ -132,19 +118,18 @@ module AdjustableSchema
 
 		def abstract? = not (source or target)
 
-		# HACK
-		# Using polymorphic associations in combination with single table inheritance (STI) is
-		# a little tricky. In order for the associations to work as expected, ensure that you
-		# store the base model for the STI models in the type column of the polymorphic
-		# association.
-		# https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#module-ActiveRecord::Associations::ClassMethods-label-Polymorphic+Associations
-		reflections
-				.values
-				.select { it.options[:polymorphic] }
-				.each do |reflection|
-					define_method "#{reflection.name}_type=" do |type|
-						super type && type.to_s.classify.constantize.base_class.to_s
-					end
-				end
+		def inspect
+			<<~TEXT.chomp.gsub(/-+/, '-')
+				#<#{self.class}##{id}: #{
+						source_type
+				}#{
+						source_id&.then { "##{it}" }
+				}>-#{name}->#{
+						target_type unless target_type == source_type and target_id
+				}#{
+						target_id&.then { "##{it}" }
+				}>
+			TEXT
+		end
 	end
 end

data/app/models/concerns/adjustable_schema/active_record/relationships/builder.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module AdjustableSchema
+	module ActiveRecord
+		module Relationships
+			module Builder # :nodoc:
+				private
+
+				def define_reference_scope direction, name
+					scope name, -> records, role: ANY do
+						joins(relationships = :"#{direction}_relationships")
+								.distinct
+								.where(
+										relationships => { id: Relationship
+												.send(Config.shortcuts[direction], records) # [to|of]: records
+												.then do
+													case role
+													when ANY
+														it
+													when nil
+														it.nameless
+													else
+														it.named *role
+													end
+												end,
+										},
+								)
+					end
+				end
+
+				def define_reference_setter direction, name
+					define_method "#{name}!" do |records, **options|
+						reference! direction => records, **options
+					end
+				end
+
+				def define_recursive_method association_name, method
+					define_method method do
+						send(association_name)
+								.recursive
+					end
+				end
+			end
+		end
+	end
+end

data/app/models/concerns/adjustable_schema/active_record/relationships.rb

@@ -5,6 +5,8 @@ require 'memery'
 module AdjustableSchema
 	module ActiveRecord # :nodoc:
 		concern :Relationships do
+			ANY = Object.new
+
 			class_methods do
 				include Memery
 
@@ -15,25 +17,29 @@ module AdjustableSchema
 				end
 
 				def roles(&) = Role.of self, &
-
-				private
-
-				def define_recursive_methods association_name, method
-					define_method method do
-						send(association_name)
-								.recursive
-					end
-				end
 			end
 
 			concern :InstanceMethods do # to include when needed
 				included do
 					scope :roleless, -> { merge Relationship.nameless }
 
+					extend Relationships::Builder
+
+					Config.association_directions.references
+							.select { reflect_on_association "#{_1}_relationships" }
+							.tap do
+								it
+										.reject { respond_to? _2 }
+										.each   { define_reference_scope _1, _2 }
+								it
+										.reject { method_defined? "#{_2}!" }
+										.each   { define_reference_setter _1, _2 }
+							end
+
 					Config.association_directions.recursive
 							.select { reflect_on_association _1 }
 							.reject { method_defined? _2 }
-							.each   { define_recursive_methods _1, _2 }
+							.each   { define_recursive_method _1, _2 }
 				end
 
 				def related?(...)
@@ -43,7 +49,6 @@ module AdjustableSchema
 
 				def related(...)
 					relationships(...)
-							.preload(Config.association_directions)
 							.map do |relationship|
 								Config.association_directions
 										.map { relationship.send it } # both objects
@@ -62,10 +67,26 @@ module AdjustableSchema
 								.map { relationships_to it }
 								.reduce(&:or)
 					end
+							.preload(Config.association_directions)
 				end
 
 				private
 
+				def reference! source: self, target: self, role: nil
+					role &&= Relationship::Role[role]
+
+					[ source, target ]
+							.map { Array it }
+							.reduce(&:product)
+							.each do |source, target|
+								Relationship.create! source:, target:, role:
+							rescue ::ActiveRecord::RecordNotUnique
+								# That’s OK, it’s already there
+							end
+
+					self # for chainability
+				end
+
 				def relationships_to direction
 					try "#{direction}_relationships" or
 							Relationship.none

data/app/models/concerns/adjustable_schema/actors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AdjustableSchema # :nodoc:
+	concern :Actors do
+		class_methods do
+			def actor?
+				Config.actor_models.any? { self <= it }
+			end
+		end
+	end
+end

data/lib/adjustable_schema/active_record/association/naming.rb

@@ -37,10 +37,24 @@ module AdjustableSchema
 					end
 				end
 
+				module Actors # :nodoc:
+					include Memery
+
+					memoize def name_with_role = {
+							source: role.name,
+							target: "#{role.name.passivize}_#{target_name}",
+					}[direction]
+
+					def name_for_any(name = object_name) = name
+							.passivize
+							.to_sym
+				end
+
 				def initialize(...)
 					super
 
 					extend Recursive if recursive?
+					extend Actors    if target.actor?
 				end
 
 				memoize def name name = object_name
@@ -77,8 +91,6 @@ module AdjustableSchema
 
 				def name_without_role = target_name
 
-				def roleless_name = name(target_name)
-
 				def name_for_any (name = object_name) = :"#{name}ful"
 				def name_for_none(name = object_name) = :"#{name}less"
 			end

data/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

data/lib/adjustable_schema/active_record/association/roleless.rb

@@ -22,6 +22,8 @@ module AdjustableSchema
 							.merge Relationship.named *roles
 				end
 			end
+
+			def roleless_name = name target_name
 		end
 	end
 end

data/lib/adjustable_schema/active_record/association.rb

@@ -15,14 +15,16 @@ module AdjustableSchema
 			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 @@ module AdjustableSchema
 
 			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 @@ module AdjustableSchema
 				}
 			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,

data/lib/adjustable_schema/active_record/builder.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module AdjustableSchema
+	module ActiveRecord
+		module Builder # :nodoc:
+			def relationship! *models, roles: [], **mapping
+				return relationship!({ **Hash[*models], **mapping }, roles:) if
+						mapping.any? # support keyword arguments syntax
+
+				case models
+				in [
+						String | Symbol | Class => source,
+						String | Symbol | Class => target,
+				]
+					define_relationship source, target,
+							roles:
+				in [ Hash => models ]
+					define_relationships models,
+							roles:
+				in [ String | Symbol | Class => model ]
+					define_recursive_relationship model,
+							roles:
+				end
+			end
+
+			def role! name
+				Relationship::Role.find_or_create_by! name:
+			end
+
+			private
+
+			def define_recursive_relationship model, roles: []
+				define_relationship model, model, roles:
+			end
+
+			def define_relationships models, roles: []
+				models
+						.flat_map { it.map { Array it }.reduce &:product }
+						.each { define_relationship *it, roles: }
+			end
+
+			def define_relationship source_type, target_type, roles: []
+				roles
+						.map { role! it }
+						.then { it.presence or [ nil ] } # no roles => nameless relationship
+						.map { |role| Relationship.create! source_type:, target_type:, role: }
+			end
+		end
+	end
+end

data/lib/adjustable_schema/active_record.rb

@@ -3,10 +3,12 @@
 module AdjustableSchema
 	module ActiveRecord # :nodoc:
 		autoload :Association, 'adjustable_schema/active_record/association'
+		autoload :Builder,     'adjustable_schema/active_record/builder'
 
 		ActiveSupport.on_load :active_record do
 			include Associations
 			include Relationships
+			include Actors
 		end
 	end
 end

data/lib/adjustable_schema/authors.rb

@@ -3,15 +3,23 @@
 Gem::Author ||= Struct.new(
 		:name,
 		:email,
-		:github_url,
-)
+		:github,
+) do
+	def github_url = github && "https://github.com/#{github}"
+end
 
-module AdjustableSchema
-	AUTHORS = [
+module AdjustableSchema # :nodoc:
+	AUTHORS = [ # rubocop:disable Style/MutableConstant
 			Gem::Author.new(
-					name:       'Alexander Senko',
-					email:      'Alexander.Senko@gmail.com',
-					github_url: 'https://github.com/Alexander-Senko',
+					name:   'Alexander Senko',
+					email:  'Alexander.Senko@gmail.com',
+					github: 'Alexander-Senko',
 			),
-	].freeze
+	]
+
+	class << AUTHORS
+		def names      = filter_map &:name
+		def emails     = filter_map &:email
+		def github_url = filter_map(&:github_url).first
+	end
 end

data/lib/adjustable_schema/config.rb

@@ -21,7 +21,8 @@ module AdjustableSchema
 				end
 			end
 
-			def self = config :self
+			def self       = config :self
+			def references = config :reference
 
 			def recursive
 				config.values.to_h do
@@ -66,6 +67,11 @@ module AdjustableSchema
 			module_function method
 		end
 
+		memoize def actor_models
+			Engine.config.actor_model_names
+					.filter_map &:safe_constantize
+		end
+
 		def association_names = Engine.config.names[:associations]
 
 		def normalize **options

data/lib/adjustable_schema/engine.rb

@@ -11,14 +11,20 @@ module AdjustableSchema
 						source: {
 								shortcut:  :of,
 								self:      :child,
+								reference: :referenced_by,
 								recursive: :descendants,
 						},
 						target: {
 								shortcut:  :to,
 								self:      :parent,
+								reference: :referencing,
 								recursive: :ancestors,
 						},
 				},
 		}
+
+		config.actor_model_names = %w[
+				User
+		]
 	end
 end

data/lib/adjustable_schema/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AdjustableSchema
-	VERSION = '0.9.0'
+	VERSION = '0.11.0'
 end

data/lib/adjustable_schema.rb

@@ -9,9 +9,15 @@ require 'rails_model_load_hook' # should be loaded
 module AdjustableSchema # :nodoc:
 	autoload :Config, 'adjustable_schema/config'
 
+	extend ActiveRecord::Builder
+
 	module_function
 
 	def available?
 		Relationship.table_exists?
 	end
+
+	def deprecator # :nodoc:
+		@deprecator ||= ActiveSupport::Deprecation.new
+	end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: adjustable_schema
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Alexander Senko
 bindir: bin
 cert_chain: []
-date: 2025-03-09 00:00:00.000000000 Z
+date: 2025-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -82,6 +82,8 @@ files:
 - app/models/adjustable_schema/relationship/role.rb
 - app/models/concerns/adjustable_schema/active_record/associations.rb
 - app/models/concerns/adjustable_schema/active_record/relationships.rb
+- app/models/concerns/adjustable_schema/active_record/relationships/builder.rb
+- app/models/concerns/adjustable_schema/actors.rb
 - config/initializers/associations.rb
 - config/initializers/model_names.rb
 - db/migrate/01_create_adjustable_schema_relationship_tables.rb
@@ -90,8 +92,10 @@ files:
 - lib/adjustable_schema/active_record/association.rb
 - lib/adjustable_schema/active_record/association/hierarchy.rb
 - lib/adjustable_schema/active_record/association/naming.rb
+- lib/adjustable_schema/active_record/association/referenced.rb
 - lib/adjustable_schema/active_record/association/roleless.rb
 - lib/adjustable_schema/active_record/association/scopes.rb
+- lib/adjustable_schema/active_record/builder.rb
 - lib/adjustable_schema/authors.rb
 - lib/adjustable_schema/config.rb
 - lib/adjustable_schema/engine.rb
@@ -103,7 +107,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/Alexander-Senko/adjustable_schema
   source_code_uri: https://github.com/Alexander-Senko/adjustable_schema
-  changelog_uri: https://github.com/Alexander-Senko/adjustable_schema/blob/v0.9.0/CHANGELOG.md
+  changelog_uri: https://github.com/Alexander-Senko/adjustable_schema/blob/v0.11.0/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib