hub_kernel 0.25.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e8e24b52cfa8070ea79fc420ec714555b3e81377725ac9ea8e8a3a20ac280bb
-  data.tar.gz: 130ba409bb6db19a6cd0d1c34ffc535407ba03255f8e282bd2f333c53bef6000
+  metadata.gz: fbd4a1ca059e2203955aab7a07510cd07620427086b6153455f0e84d1f4ea639
+  data.tar.gz: 26a9be066b129fa83177261e5f9e15cc72c206c3210dc4fc1f26c6a65ac29676
 SHA512:
-  metadata.gz: d159cfc7e9b03980d03de84433ca09d3f1b5a11d758b10a3412a54eff96b8636b1187d9b2e4d54d2582ef7610d43c8df0e63c8a99de1553f17cb698175b34e9a
-  data.tar.gz: 7e075af8fa7fbe2cc6b7952a45c5a710c7702a39686cf38b0b121166c39f89f06f53e3e9114e3543e606cb22e9628c42ca09f96ba70ceafe31922b74bf491dce
+  metadata.gz: 80bcd028c34e3be272d7c81b81852a0814c592df1cdbfb58954095dc4f240db87d02e4cd78afebd7cec0a0a9d1212d5f0585203724eefab74e81d42901b43050
+  data.tar.gz: 782767a253efd77447d8be7b2d16dc7086f8715515d19189435cb4a4fc5c64663cb25e721e2056fd19356b82b84b742bfbedab434652b6030a5a9c21fb41323c

data/README.md

@@ -167,6 +167,52 @@ the app fills the port with.
 The model names only its own hub, so the crossing check passes it. The app's
 `to_prepare` block that fills the port is the one place both models are named.
 
+### Has-many links through a record port
+A hub's model lists the records another hub owns that point back at it with
+`has_many_port`, naming its own hub and one of that hub's record ports:
+
+```ruby
+module Sales
+  class Job < ApplicationRecord
+    has_many_port :quotes, port: Sales, record: :quote_record
+  end
+end
+```
+
+hub_kernel defines an ordinary `has_many :quotes` whose class is the model the app filled
+the port with. `job.quotes` lists the quotes, and `includes`, `preload`, `joins`, `where`
+and `order` work on the link as on any `has_many`. Every other `has_many` option, such as
+`foreign_key:` or `inverse_of:`, and a scope passed before the options, reach the
+association unchanged, apart from the options below that write to the listed records.
+The class name comes from the port, so one passed is not used.
+
+A has-many link is always read-only, and no option makes it writable:
+
+- A record listed through the link, loaded, preloaded or queried, raises
+  `ActiveRecord::ReadOnlyRecord` when it is saved or destroyed.
+- Adding a record to the list with `<<`, `push`, `append`, `concat` or `replace`, removing
+  one with `delete`, `destroy`, `delete_all`, `destroy_all` or `clear`, and building or
+  creating one with `build`, `new`, `create` or `create!` raise
+  `ActiveRecord::ReadOnlyRecord`, on the list and on a query made from it.
+- Assigning the list with `quotes=` or `quote_ids=` raises `ActiveRecord::ReadOnlyRecord`.
+- Writing the listed records all at once with `update_all`, `update_counters`, `insert`,
+  `insert!`, `insert_all`, `insert_all!`, `upsert` or `upsert_all` raises
+  `ActiveRecord::ReadOnlyRecord`.
+- `autosave`, `counter_cache` and a `dependent` value that destroys, deletes or nullifies
+  the listed records each write to them, so passing any of them raises an `ArgumentError`
+  naming it.
+
+`dependent: :restrict_with_exception` and `dependent: :restrict_with_error` write nothing
+to the listed records, so the link takes them. Deleting the model while the link lists
+records is refused, the first way by raising `ActiveRecord::DeleteRestrictionError` and
+the second by adding an error and returning false, and deleting it when the link lists
+none goes ahead.
+
+The link is defined as soon as both the model has loaded and the port is filled, in
+whichever order those happen, the same way as a `belongs_to_port` link. A boot with eager
+loading on defines it, and after a code reload in development the reloaded model lists
+the reloaded model the app fills the port with.
+
 ### The start check
 Every hub that declares a port or exposes a method is on `HubKernel::Hubs.list`. Call
 `HubKernel::Hubs.check!` after the app fills its ports, and the app refuses to start

data/lib/hub_kernel/port_associations.rb

@@ -1,6 +1,9 @@
 module HubKernel
   module PortAssociations
     WRITING_OPTIONS = %i[autosave dependent touch counter_cache].freeze
+    LIST_WRITING_OPTIONS = %i[autosave dependent counter_cache].freeze
+    RESTRICTING = %i[restrict_with_error restrict_with_exception].freeze
+    LIST_WRITING_METHODS = %i[<< push append concat build new create create! delete destroy delete_all destroy_all clear replace update_all insert insert! insert_all insert_all! upsert upsert_all].freeze
 
     def belongs_to_port(name, scope = nil, port:, record:, **options)
       refuse_writing_options(name, options)
@@ -10,18 +13,35 @@ module HubKernel
       end
     end
 
+    def has_many_port(name, scope = nil, port:, record:, **options)
+      refuse_writing_options(name, options.reject { |option, value| option == :dependent && RESTRICTING.include?(value) }, LIST_WRITING_OPTIONS)
+      refusal = "#{self.name}'s #{name} link is read-only, so no record can be written through it"
+      port.link_record(record, [ self.name, name ]) do |model|
+        has_many name, read_only(scope, refusing_list(refusal)), **options, class_name: model.name
+        refuse_replacing_list(name, refusal)
+      end
+    end
+
     private
 
-    def refuse_writing_options(name, options)
-      writing = options.keys & WRITING_OPTIONS
+    def refuse_writing_options(name, options, writers = WRITING_OPTIONS)
+      writing = options.keys & writers
       raise ArgumentError, "#{name} is a read-only record port link, so it does not take #{writing.to_sentence}" if writing.any?
     end
 
-    def read_only(scope)
-      return -> { readonly } unless scope
-      return -> { instance_exec(&scope).readonly } if scope.arity.zero?
+    def read_only(scope, *extensions)
+      return -> { readonly.extending(*extensions) } unless scope
+      return -> { instance_exec(&scope).readonly.extending(*extensions) } if scope.arity.zero?
+
+      ->(owner) { instance_exec(owner, &scope).readonly.extending(*extensions) }
+    end
+
+    def refusing_list(refusal)
+      Module.new { LIST_WRITING_METHODS.each { |method| define_method(method) { |*| raise ActiveRecord::ReadOnlyRecord, refusal } } }
+    end
 
-      ->(owner) { instance_exec(owner, &scope).readonly }
+    def refuse_replacing_list(name, refusal)
+      [ :"#{name}=", :"#{name.to_s.singularize}_ids=" ].each { |method| define_method(method) { |*| raise ActiveRecord::ReadOnlyRecord, refusal } }
     end
 
     def refuse_creating_through(name)

data/lib/hub_kernel/version.rb

@@ -1,3 +1,3 @@
 module HubKernel
-  VERSION = "0.25.0"
+  VERSION = "0.26.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hub_kernel
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.26.0
 platform: ruby
 authors:
 - tylercschneider