conjunction 0.20.2 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6d5c16ce29ac6addec81af2221485e531d9efffd99f9ec059672063190c84c0
-  data.tar.gz: a2ce500f63fd7bd00c200e4181f5e92a4371884e0a49b79787ffabbde95186fa
+  metadata.gz: 29f3f2cc286036dc191c0e25fb9add5e66641c12c874d96726ac7edaec31ef38
+  data.tar.gz: 29d161b6a36913ea34e11e0d7ffd20f98d6144b50cdbad6303344919ee088ab6
 SHA512:
-  metadata.gz: 2ae90365cd6d8f2d7d0958da89d7296a674097c9b2554e55373301ea5a82e2019b11291097ce6068f0c31a6ba6a6537e1760f09829bfa273e0e221982722f3f3
-  data.tar.gz: c2276b3def46f6134c74a3182fb14ed7d305a8f32ab77b92c0bdd7fb8f6c744ae4c4d35642681c93e2dbbbf9ffadb2220646d4617592ee425ece6fa6c466606e
+  metadata.gz: c1888c5f4669520ee7028216dfbbb2f944ec20fe2a97e1bfc4ce6d04f1d58c4f0295103fd7e5c67fa7427f79c56be7d4b80ce54f11d258a41d6f5e6a65d669fc
+  data.tar.gz: 6d12506c38b16fa38fce51759b0f78f6c611cc45c3cc8453cc0a60bb0526339e930595dd17f0be19a987497a6b23d40368082f5376287e5cf4e4dabc1d6a0f82

data/README.md

@@ -1,6 +1,6 @@
 # Conjunction
 
-Create cacheable collections of filtered, sorted, and paginated ActiveRecord objects.
+Join together related concepts for a common purpose with Conjugation.
 
 [![Gem Version](https://badge.fury.io/rb/conjunction.svg)](https://badge.fury.io/rb/conjunction)
 [![Build Status](https://semaphoreci.com/api/v1/freshly/spicerack/branches/master/badge.svg)](https://semaphoreci.com/freshly/spicerack)
@@ -8,7 +8,18 @@ Create cacheable collections of filtered, sorted, and paginated ActiveRecord obj
 [![Test Coverage](https://api.codeclimate.com/v1/badges/7e089c2617c530a85b17/test_coverage)](https://codeclimate.com/github/Freshly/spicerack/test_coverage)
 
 * [Installation](#installation)
-* [Usage](#usage)
+* [QuickStart Guide](#quickstart-guide)
+* [Gem Developer Usage](#gem-developer-usage)
+   * [On the Separation of Concerns](#on-the-separation-of-concerns)
+   * [Why does this exist?](#why-does-this-exist)
+   * [How's it Function?](#hows-it-function)
+   * [Digging In](#digging-in)
+   * [On Naming Conventions](#on-naming-conventions)
+      * [Backreference](#backreference)
+      * [Bi-direction Cross-Reference](#bi-direction-cross-reference)
+* [Configuration](#configuration)
+   * [Explicit vs Override](#explicit-vs-override)
+   * [Nexus](#nexus)
 * [Development](#development)
 * [Contributing](#contributing)
 * [License](#license)
@@ -29,9 +40,705 @@ Or install it yourself as:
 
     $ gem install conjunction
 
-## Usage
+## QuickStart Guide
 
-TODO: Write usage instructions here
+Let's say you have an `Order`:
+
+```ruby
+class Order < ApplicationRecord
+  def self.service_class
+    OrderService
+  end
+end
+```
+
+Which descends from an `ApplicationRecord`:
+
+```ruby
+class ApplicationRecord
+  def to_service
+    self.class.service_class.new(self)
+  end
+end
+```
+
+And you have an `OrderService`:
+
+```ruby
+class OrderService < ApplicationService
+  # ...software be here...
+end
+```
+
+Which descends from an `ApplicationService`:
+      
+```ruby
+class ApplicationService
+  def initialize(object)
+    @object = object
+  end
+end
+```
+
+Use `Conjunction` to tell your Records they can be related (called a Conjunctive):
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  include Conjunction::Conjunctive
+end
+```
+
+And your services that they are a kind of relation with a naming convention (called a Junction):
+
+```ruby
+class ApplicationService
+  include Conjunction::Junction
+  prefixed_with "Service"
+end
+```
+
+Now your can look up related objects (like services) implicitly from your objects:
+
+```ruby
+class ApplicationRecord
+  def to_service
+    conjugate(ApplicationService)&.new(self)
+  end
+end
+```
+
+And remove all the implicit boilerplate which could be assumed:
+
+```ruby
+class Order < ApplicationRecord; end
+
+Order.conjugate(ApplicationService) # => OrderService
+```
+
+And then in the future, any new objects you create which follow convention "just work":
+
+```ruby
+class Foo < ApplicationRecord; end
+class FooService < ApplicationService; end
+
+Foo.conjugate(ApplicationService) # => FooService
+```
+
+You can also quickly an easily configure relationships explicitly, either directly:
+
+```ruby
+class Foo < ApplicationRecord
+  conjoins BarService
+end
+
+Foo.conjugate(ApplicationService) # => BarService
+```
+
+Or through a central routing file called a `Nexus`:
+
+```ruby
+# config/initializers/conjunction_nexus.rb
+class Conjunction::Nexus
+  couple Foo, to: GazService
+end
+
+Foo.conjugate(ApplicationService) # => GazService
+```
+
+You may also be interested in reading through the [Configuration](#configuration) docs.
+
+## Gem Developer Usage
+
+🚨 **Note**: This is a middleware gem designed to help gem developers or folks with lots of custom DSL objects build them in a cleaner and more standardized way. It is **NOT** expected that most application developers will need to be aware of this gem's existence or configuration!
+
+### On the Separation of Concerns
+
+Consider the following:
+
+```ruby
+class User < ApplicationRecord
+  validates :first_name, :last_name, length: { minimum: 2 }, presence: true
+  
+  def initials
+    "#{first_name.chr}#{last_name.chr}"
+  end
+  
+  def name
+    "#{first_name} #{last_name}"
+  end
+  
+  # conventional name in application for displaying in subjects in views
+  def display_name
+    name
+  end
+  
+  # name used when this user sends emails to others on platforms
+  def email_from_name
+    name
+  end  
+  
+  # name used when addressing this user in emails (obviously...)
+  def email_to_name
+    first_name
+  end
+  
+  # vestigial code used in the legacy half of the app... smh
+  def nickname
+    last_name
+  end
+end
+```
+
+This object has very poor [Separation of Concerns](https://en.wikipedia.org/wiki/Separation_of_concerns); it obligates much of the application while providing little value at the cost of extraneous code.
+
+```ruby
+class User < ApplicationRecord
+  include PersonNameable
+  include NamedPresentable
+  include NamedPersonEmailAddressable
+  
+  # vestigial code used in the legacy half of the app... smh
+  def nickname
+    last_name
+  end
+end
+```
+
+This kinda looks nicer. Until you look at the consequential under-the-hood code:
+
+```ruby
+module PersonNameable
+  extend ActiveSupport::Concern
+  
+  included do 
+    validates :first_name, :last_name, length: { minimum: 2 }, presence: true
+  end
+  
+  def initials
+    "#{first_name.chr}#{last_name.chr}"
+  end
+
+  def name
+    "#{first_name} #{last_name}"
+  end
+end
+
+module NamedPresentable
+  extend ActiveSupport::Concern
+  
+  # conventional name in application for displaying in subjects in views, assume name
+  def display_name
+    name
+  end
+end
+
+module NamedPersonEmailAddressable
+  extend ActiveSupport::Concern
+  
+  # name used when this user sends emails to others on platforms
+  def email_from_name
+    name
+  end  
+  
+  # name used when addressing this user in emails (obviously...)
+  def email_to_name
+    first_name
+  end
+end
+```
+
+And recognize that `user.email_to_name` is still a valid method. This object STILL has very poor `Separation of Concerns` but in this form also suffers from a much higher [Connascence](https://en.wikipedia.org/wiki/Connascence)! OH NO! 😭
+
+⭐️ That's because **Separation of Concerns** applies to your object architecture *NOT* your file system!
+
+An object architecture with properly separated concerns would look more like this:
+
+```ruby
+class User
+  validates :first_name, :last_name, length: { minimum: 2 }, presence: true
+  
+  def initials
+    "#{first_name.chr}#{last_name.chr}"
+  end
+  
+  def name
+    "#{first_name} #{last_name}"
+  end
+  
+  # vestigial code used in the legacy half of the app... smh
+  def nickname
+    last_name
+  end
+end
+```
+
+```ruby
+class UserPresenter
+  def initialize(user)
+    @user = user
+  end
+  
+  def display_name
+    user.name
+  end
+end
+
+class UserEmailSender
+  def initialize(user)
+    @user = user
+  end
+  
+  def from_name
+    user.name
+  end
+end
+
+class UserEmailRecipient
+  def initialize(user)
+    @user = user
+  end
+  
+  def to_name
+    user.first_name
+  end
+end
+```
+
+Now, the `User` object has no need to know about email sending or receiving, nor whatever naming standards the application has adopted around presenting objects to users.
+
+This is a nominal pattern adopted by several gems in the rails ecosystem: [ActiveModelSerializers](https://github.com/rails-api/active_model_serializers/tree/0-10-stable), [Draper](https://github.com/drapergem/draper), [Pundit](https://github.com/varvet/pundit) to name a few.
+
+Enter `Conjunction`, a gem for managing the coupling of properly separated object concerns.
+
+### Why does this exist?
+
+Let's imagine we're building a standardized presenter gem for displaying models:
+
+```ruby
+class ApplicationPresenter
+  def initialize(model)
+    @model = model
+  end
+  
+  def name
+    I18n.t("unknown")
+  end
+end
+```
+
+And we want to create a specialized class for displaying a specific model:
+
+```ruby
+class UserPresenter < ApplicationPresenter
+  def name
+    I18n.t("format_greetings.#{user.greeting_type}", user.name)
+  end
+end
+```
+
+So the first question is how a `User` know about it's presenter.
+
+One option is direct reference:
+
+```ruby
+class User < ApplicationRecord
+  def to_presenter
+    UserPresenter.new(self)
+  end
+end
+```
+
+This leverages `Connascence of Name (CoN)` which is the weakest (and therefore most ideal) reference.
+
+And this solution is nice, but it gets kind of messy at scale:
+
+```ruby
+class User < ApplicationRecord
+  def to_presenter
+    UserPresenter.new(self)
+  end
+  
+  def to_serializer
+    UserSerializer.new(self)
+  end
+  
+  def to_policy
+    UserPolicy.new(self)
+  end
+end
+```
+
+Especially when you add in the complexity of class AND/OR instance reference:
+
+```ruby
+class User < ApplicationRecord
+  class << self
+    def to_presenter
+      UserList.new
+    end
+    
+    def to_policy
+      UserPolicy.new
+    end
+  end
+  
+  def to_presenter
+    UserPresenter.new(self)
+  end
+  
+  def to_serializer
+    UserSerializer.new(self)
+  end
+  
+  def to_policy
+    UserPolicy.new(self)
+  end
+end
+```
+
+For just three related objects we're at 20 lines of code added to potentially `N` models in the ecosystem.
+
+This also creates other problems, such as dissimilarity in reference, a model without a presenter will not define a `to_presenter` method, so generic code:
+
+```ruby
+model.to_presenter # => raise NoMethodError ?!
+```
+
+To get around this, you now need to put some kind of generic handling in the base object:
+
+```ruby
+class ApplicationRecord
+  class << self
+    def to_presenter
+      nil
+    end
+    
+    def to_policy
+      raise "all records must have a policy"
+    end
+  end
+  
+  def to_presenter
+    null
+  end
+  
+  def to_serializer
+    raise "all records must have a serializer"
+  end
+  
+  def to_policy
+    raise "all records must have a policy"
+  end
+end
+```
+
+This also obviously isn't a possibility if you are writing a third party gem to introduce a "kind" of object into the system, and the example gems have all solved this problem differently:
+
+`ActiveModelSerializers` conjured up the [LookupChain](https://github.com/rails-api/active_model_serializers/blob/0-10-stable/lib/active_model_serializers/lookup_chain.rb), `Draper` went the concern route with [decoratable](https://github.com/drapergem/draper/blob/master/lib/draper/decoratable.rb) and `Pundit` evolved the [PolicyFinder](https://github.com/varvet/pundit/blob/master/lib/pundit/policy_finder.rb).
+
+All these are very disparate and feature-rich implementations of a solution to the problem. All of them offering at least some configurability to control how the lookup occurred to translate the kind of "root" model object into its related SoC object.
+
+So ultimately, `Conjunction` exists because I thought it would be nice to create a generic solution to this object reference problem that can be utilized by other gems to create some kind of standardization and consistency to this hard problem.
+
+It also selfishly helps cleanup a lot of duplicate code across several co-developed gems which I will shamelessly plug here: [Command](https://github.com/Freshly/command), [Facet](https://github.com/Freshly/spicerack/tree/develop/facet), [Flow](https://github.com/Freshly/flow), [Law](https://github.com/Freshly/law), [Material](https://github.com/Freshly/material).
+
+### How's it Function?
+
+In `Conjunction` there are two distinct concepts: **Prototypes** and **Conjugates**.
+
+A **Prototype** is unitary (named without a prefix or suffix) and represents the core object around which concerns are being separated, in the above example `User`.
+
+A **Conjugate** is the `SoC` object which encapsulates the other behaviors or information, in the above example `UserPresenter`; named after the linguistic process that gives the different forms of an verb as they vary according to voice, mood, tense, etc. 
+
+Generally speaking, the community assumption peddled by the ActiveModelSerializers, Drapers, and Pundits of the world seems to be a suffixed naming convention; `AuthorSerializer` for an `Author` class, `ArticleDecorator` for an `Article` class, `UserPolicy` for a `User` class.
+
+`Conjunction` defines a `.conjugate` **Prototypes** class method to allow the lookup of **Conjugate** objects given their base classes:
+
+```ruby
+Author.conjugate(ApplicationSerializer) # => AuthorSerializer
+Article.conjugate(ApplicationDecorator) # => ArticleDecorator
+User.conjugate(ApplicationPolicy)       # => UserPolicy
+```
+
+### Digging In
+
+`Conjunction` leverages two main concerns: **Conjunctives** and **Junctions**.
+
+A **Conjunctive** is the generic base class from which your **Prototype** descends, in the above example `ApplicationRecord` is the **Conjunctive** for the `User` **Prototype**.
+
+```ruby
+class ApplicationRecord
+  include Conjunction::Conjunctive
+end
+```
+
+This grants `ApplicationRecord` the ability to represent itself as a **Prototype**, the primary requirement of which is to define a `.prototype_name` method (which by default is simply the class name):
+
+```ruby
+User.prototype_name # => User
+User.first.prototype_name # => User
+```
+
+A **Junction** is the generic base class from which any **Conjugate** object descends, in the above example `ApplicationPresenter` is the **Junction** for the `UserPresenter` **Conjugate**.
+
+```ruby
+class ApplicationPresenter
+  include Conjunction::Junction
+end
+```
+
+This grants `ApplicationPresenter` the ability to reference a **Prototype** and find a related **Conjugate**; also it allows you to write `Conjunction::Junction` and commit it into a production application for serious, which is a total bonus feature 🤩.
+
+The primary requirement of a `Junction` is to define a `.junction_key` which should be unique among your `SoC` objects. 
+
+🚨 **WARNING**: By default, your Junctions **WILL NOT** define a junction key!
+
+You can explicitly define a junction key:
+
+```ruby
+class ApplicationPresenter
+  include Conjunction::Junction
+  
+  class << self
+    def junction_key
+      :any_key_u_want
+    end
+  end
+end
+```
+😽‍ *Super Lazy??*: Good News, so am I! There are default junction keys!
+
+### On Naming Conventions
+
+Given the community standard of `FooBarThing` naming convention for `Things`, there is an assumption that most applications will attempt to keep a minimal `Connascence of Name (CoN)` approach; usually for any given `FooBar` you would expect it's `Thing` to be a `FooBarThing`.
+
+You can **and should** define your expected naming convention on your Junctions:
+
+```ruby
+class ApplicationPresenter
+  include Conjunction::Junction
+  suffixed_with "Presenter"
+end
+```
+
+This now gives the `Presenter` junction enough information to know that it's naming convention is `#{prototype_name}Presenter`. It also provides enough unique identifying information to assume the `junction_key` as an underscored version of the suffix:
+
+```ruby
+ApplicationPresenter.junction_key # => presenter
+```
+
+You can also use `suffixed_with` if you want to do namespaces instead, ex:
+
+```ruby
+class ApplicationFleeb
+  include Conjunction::Junction
+  suffixed_with "Grundus::Fleeb::"
+end
+```
+
+This now assumes that a `Foo` prototype will have a `Grundus::Fleeb::Foo` conjugate.
+
+💁‍ *Note*: You can use both a `suffix` and `prefix` together; the junction key will be `#{suffix}_#{prefix}`.
+
+You can also override the default by setting it to a blank string in a descendant class:
+
+```ruby
+class PresenterBase
+  include Conjunction::Junction
+  suffixed_with "Presenter"
+end
+
+class ApplicationPresenter < Base::Presenter
+  suffixed_with ""
+  prefixed_with "Presenter::"
+end
+```
+
+#### Backreference
+
+Naming Conventions are necessary to facilitate "best guess lookup" and therefore if a Conjugate name can be intuited by the naming convention, a Prototype name can be distilled from it:
+
+```ruby
+UserPresenter.prototype_class # => User
+Grundus::Fleeb::User.prototype_class # => User
+```
+
+This allows valuable class level introspection into relationships which can be quickly and easily put under test:
+
+```ruby
+RSpec.describe User do 
+  it { is_expected.to conjugate_into UserPresenter }
+  it { is_expected.to conjugate_into Grundus::Fleeb::User }
+end
+```
+
+From either side of the equation (ideally, both!):
+
+```ruby
+RSpec.describe UserPresenter do 
+  it { is_expected.to be_conjugated_from User }
+end
+```
+
+```ruby
+RSpec.describe Grundus::Fleeb::User do 
+  it { is_expected.to be_conjugated_from User }
+end
+```
+
+#### Bi-direction Cross-Reference
+
+An even more interesting side-effect of backreference in the nominal case is Bi-direction Cross-Reference. Two Junctions which are conjugates of a given prototype can be directly conjugated into each other!
+
+```ruby
+UserPresenter.conjugate(ApplicationFleeb) # => Grundus::Fleeb::User
+Grundus::Fleeb::User.conjugate(ApplicationPresenter) # => UserPresenter
+```
+
+What's *really* interesting is that you don't even *need* a user class to really exist for this kind of behavior to manifest! The above snippet works even when `defined?(User) == false`!!
+
+## Configuration
+
+`Conjunction` expects that a well-thought-out (or at least standardized) naming convention can get you a long way, but given software is hard there must be some mechanism for overrides. 
+
+So it might surprise you to find that no mechanism has been exposed to override `Conjunction`! 
+
+It will *always* run in implicit lookup mode where it attempts to use the naming convention of objects as it understands them to intuit the coupling relationships of your application. 
+
+It *can* be configured **NOT** to perform implicit lookup at all if you hate the idea of magic names "just working":
+
+```ruby
+# config/initializers/conjunction.rb
+Conjunction.configure do |config|
+  config.disable_all_implicit_lookup = true
+end
+```
+
+### Explicit vs Override
+
+Instead of overriding implicit lookup, you can simply explicitly define conjunctions.
+
+To directly tell any Conjunctive how it is related to its conjugates, use `.conjoins`:
+
+```ruby
+class User < ApplicationRecord
+  conjoins UserPresenter
+  conjoins Grundus::Fleeb::User
+  conjoins UserPolicy
+end
+```
+
+⚠️ **WARNING**: You can only provide objects which are valid `Conjunction::Junctions` to the `.conjoins` method; any object without a valid `junction_key` will raise an exception.
+
+It is this explicit reference mechanism that exists for you to "override" the default coupling rules of your application: 
+
+```ruby
+class User < ApplicationRecord
+  conjoins GenericPresenter
+  conjoins Grundus::Fleeb::Dinglebop
+  conjoins AdminOnlyEditOpenViewPolicy
+end
+```
+
+This has the direct and immediate effect of altering what conjugates are returned:
+
+```ruby
+User.conjugate(ApplicationPresenter) # => GenericPresenter
+User.conjugate(ApplicationFleeb) # => Grundus::Fleeb::Dinglebop
+User.conjugate(ApplicationPolicy) # => AdminOnlyEditOpenViewPolicy
+```
+
+This is true EVEN IF you have valid naming-convention-assumed objects that exist. For example, even if there was a `UserPresenter` the immediate example above would return a `GenericPresenter`. This can best be seen in this example:
+
+```ruby
+User.conjugate(UserPresenter) # => GenericPresenter
+```
+
+Even giving the object what you assume the destination presenter would be, it's conjugate follows the explicit naming rules!
+
+💁‍ **Note**: You can use `.conjoins` only when you need to override the otherwise "default" implicit naming conventions. This "explicit as override" methodology is the recommended way to use `Conjunction`, as it calls attention to "what's different" while letting normal "ust work". It also prevents you from having to define an object AND remember to relate it.
+
+```ruby
+class User < ApplicationRecord
+  conjoins AdminOnlyEditOpenViewPolicy
+end
+```
+
+Given an expected presence of other objects, this would work as follows:
+
+```ruby
+User.conjugate(ApplicationPresenter) # => UserPresenter
+User.conjugate(ApplicationFleeb) # => Grundus::Fleeb::User
+User.conjugate(ApplicationPolicy) # => AdminOnlyEditOpenViewPolicy
+```
+
+### Nexus
+
+In what is arguably the coolest class name I've ever written, you can define a central routing nexus which acts as a central source of truth for all the object relationships in your application.
+
+Create a `config/initializers/conjunction_nexus.rb` file like so:
+
+```ruby
+class Conjunction::Nexus
+  couple Foo, to: CommonMaterial
+  couple Bar, to: CommonMaterial
+
+  couple FooFlow, to: FooState, bidirectional: true
+end
+```
+
+The `bidirectional: true` flag above is the DRY form of this equivalent assignment:
+
+```ruby
+class Conjunction::Nexus
+  couple FooFlow, to: FooState
+  couple FooState, to: FooFlow
+end
+```
+
+The `Nexus` file is a "best of both worlds" approach if you want to keep your models (conjunctives) limited in what they outwardly need to know about their other conjunctive forms without bloating each model individually.
+
+💁‍ **Note**: If you make use of the nexus file and want to enforce explicit lookup behavior in your application, there is a special configuration option to disable implicit lookup for any classes which are defined within the nexus using the `nexus_use_disables_implicit_lookup` flag:
+
+```ruby
+# config/initializers/conjunction.rb
+Conjunction.configure do |config|
+  config.nexus_use_disables_implicit_lookup = true
+end
+```
+
+Now, if you define something within the nexus for any given type of junction, ALL junctions need to follow suite:
+
+```ruby
+# Given `FooPresenter`, `BarPresenter`, `Foo`, and `Bar`:
+class Conjunction::Nexus
+  couple Foo, to: FooPresenter
+end 
+
+# With `nexus_use_disables_implicit_lookup` false:
+Foo.conjoins(ApplicationPresenter) # => FooPresenter
+Bar.conjoins(ApplicationPresenter) # => BarPresenter
+
+# With `nexus_use_disables_implicit_lookup` true:
+Foo.conjoins(ApplicationPresenter) # => FooPresenter
+Bar.conjoins(ApplicationPresenter) # => nil
+```
+
+💁‍ **Note**: Nexus configuration is a "kind" of explicit configuration and shouldn't be mixed with conflicting information on the object itself:
+
+```ruby
+class Conjunction::Nexus
+  couple Foo, to: FooPresenter
+end 
+
+class Foo < ApplicationRecord
+  conjoins BarPresenter
+end
+```
+
+In the above example, `Foo.conjoins(ApplicationPresenter)` would be `BarPresenter` as the configuration closest to the object takes precedence, but this is a really weird and not very expected behavior that is left intact "in-case you really need it". 
+
+The overall recommendation here is to "pick a horse" and either use a Nexus file OR use explicit object level definitions for overrides.
 
 ## Development
 

data/lib/conjunction/configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Conjunction
+  module Configuration
+    extend Spicerack::Configurable
+
+    configuration_options do
+      option :nexus_use_disables_implicit_lookup, default: false
+      option :disable_all_implicit_lookup, default: false
+    end
+  end
+end

data/lib/conjunction/conjunctive.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Conjunction
+  # **Conjunctives** are **Prototypes** that can be `conjugated` with a **Junction** into a specific **Conjunction**.
+  module Conjunctive
+    extend ActiveSupport::Concern
+
+    include Conjunction::Prototype
+
+    included do
+      class_attribute :explicit_conjunctions, instance_writer: false, default: {}
+
+      delegate :conjugate, :conjugate!, to: :class
+    end
+
+    class_methods do
+      def conjugate(junction)
+        conjugate_with(junction, :conjunction_for)
+      end
+
+      def conjugate!(junction)
+        conjugate_with(junction, :conjunction_for!)
+      end
+
+      def inherited(base)
+        base.explicit_conjunctions = {}
+        super
+      end
+
+      private
+
+      def conjugate_with(junction, method_name)
+        conjunction = explicit_conjunctions[junction.try(:junction_key)] || Nexus.conjugate(self, junction: junction)
+        return conjunction if conjunction.present?
+
+        return if Conjunction.config.nexus_use_disables_implicit_lookup && Nexus.couples?(junction)
+
+        junction.try(method_name, prototype, prototype_name) unless Conjunction.config.disable_all_implicit_lookup
+      end
+
+      def conjoins(junction)
+        raise TypeError, "#{junction} is not a valid junction" unless junction.respond_to?(:junction_key)
+
+        explicit_conjunctions[junction.junction_key] = junction
+      end
+    end
+  end
+end

data/lib/conjunction/junction.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Conjunction
+  # A **Junction** is an encapsulation of behavior which has been abstracted out of a **Conjunctive**.
+  module Junction
+    extend ActiveSupport::Concern
+
+    include Conjunction::Conjunctive
+    include Conjunction::NamingConvention
+
+    included do
+      delegate :conjunction_for!, :conjunction_for, :conjunction_name_for, to: :class
+    end
+
+    class_methods do
+      def junction_key
+        key_parts.join.underscore.parameterize(separator: "_").to_sym if conjunctive?
+      end
+
+      def prototype_name
+        output = name
+        output.slice!(conjunction_prefix) if conjunction_prefix?
+        output.chomp!(conjunction_suffix) if conjunction_suffix?
+        output unless output == name
+      end
+
+      def conjunction_for!(other_prototype, prototype_name)
+        conjunction_for(other_prototype, prototype_name) or raise DisjointedError, "#{other_prototype} #{name} unknown"
+      end
+
+      def conjunction_for(other_prototype, prototype_name)
+        conjunction_name_for(other_prototype, prototype_name)&.safe_constantize
+      end
+
+      private
+
+      def key_parts
+        [ conjunction_prefix, conjunction_suffix ].compact
+      end
+
+      def conjunction_name_for(other_prototype, other_prototype_name)
+        other_prototype_name = other_prototype.prototype_name if other_prototype.respond_to?(:prototype_name)
+        return if other_prototype_name.blank?
+
+        [ conjunction_prefix, other_prototype_name, conjunction_suffix ].compact.join if conjunctive?
+      end
+    end
+  end
+end

data/lib/conjunction/naming_convention.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Conjunction
+  # A **NamingConvention** defines the name formatting of a given **Junction**.
+  module NamingConvention
+    extend ActiveSupport::Concern
+
+    class_methods do
+      attr_reader :conjunction_prefix, :conjunction_suffix
+
+      def conjunctive?
+        conjunction_prefix? || conjunction_suffix?
+      end
+
+      def conjunction_prefix?
+        conjunction_prefix.present?
+      end
+
+      def conjunction_suffix?
+        conjunction_suffix.present?
+      end
+
+      def inherited(base)
+        base.prefixed_with(conjunction_prefix) if conjunction_prefix?
+        base.suffixed_with(conjunction_suffix) if conjunction_suffix?
+        super
+      end
+
+      protected
+
+      def prefixed_with(prefix)
+        raise TypeError, "prefix must be a string" if prefix.present? && !prefix.is_a?(String)
+
+        @conjunction_prefix = prefix
+      end
+
+      def suffixed_with(suffix)
+        raise TypeError, "suffix must be a string" if suffix.present? && !suffix.is_a?(String)
+
+        @conjunction_suffix = suffix
+      end
+    end
+  end
+end

data/lib/conjunction/nexus.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Conjunction
+  # The Nexus provides a central source to couple objects together explicitly:
+  #
+  #     class Conjunction::Nexus
+  #       couple Foo, to: CommonMaterial
+  #       couple Bar, to: CommonMaterial
+  #
+  #       couple FooFlow, to: FooState, bidirectional: true
+  #     end
+  #
+  class Nexus
+    include Singleton
+
+    class_attribute :_couplings, instance_writer: false, default: Hash.new { |hash, key| hash[key] = {} }
+
+    class << self
+      def conjugate(conjunctive, junction:)
+        _couplings[junction.try(:junction_key)][conjunctive] if couples?(junction)
+      end
+
+      def couples?(junction)
+        _couplings.key?(junction.try(:junction_key))
+      end
+
+      private
+
+      def couple(conjunctive, to:, bidirectional: false)
+        raise TypeError, "#{conjunctive} is not a valid conjunctive" unless conjunctive.respond_to?(:conjugate)
+        raise TypeError, "#{to} is not a valid junction" unless to.respond_to?(:junction_key)
+
+        if bidirectional
+          raise TypeError, "#{conjunctive} is not a valid junction" unless conjunctive.respond_to?(:junction_key)
+
+          _couplings[conjunctive.junction_key][to] = conjunctive
+        end
+
+        _couplings[to.junction_key][conjunctive] = to
+      end
+    end
+  end
+end

data/lib/conjunction/prototype.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Conjunction
+  # A **Prototype** is a uniquely named Object with behavior which has been abstracted out into **Junction** classes.
+  module Prototype
+    extend ActiveSupport::Concern
+
+    included do
+      delegate :prototype_name, :prototype, :prototype!, to: :class
+    end
+
+    class_methods do
+      def prototype!
+        prototype or raise NameError, "#{prototype_name} is not defined"
+      end
+
+      def prototype
+        prototype_name&.safe_constantize
+      end
+
+      def prototype_name
+        try(:model_name)&.name || name
+      end
+    end
+  end
+end

data/lib/conjunction/rspec/custom_matchers/be_conjoined_to.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# RSpec matcher that tests usage of `.conjoins`
+#
+#     class Foo < ApplicationRecord
+#       conjoins GenericFleeb
+#     end
+#
+#     class GenericFleeb < ApplicationFleeb; end
+#
+#     RSpec.describe Foo, type: :model do
+#       it { is_expected.to be_conjoined_to GenericFleeb }
+#     end
+
+RSpec::Matchers.define :be_conjoined_to do |junction|
+  match { |subject| expect(subject.explicit_conjunctions[junction.junction_key]).to eq junction }
+  description { "be conjoined to #{junction}" }
+  failure_message { |subject| "expected #{subject} to be conjoined to #{junction} but wasn't" }
+end

data/lib/conjunction/rspec/custom_matchers/be_conjugated_from.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# RSpec matcher that tests usage of `.conjugate`
+#
+#     class Foo < ApplicationRecord
+#       conjoins GenericFleeb
+#     end
+#
+#     class GenericFleeb < ApplicationFleeb; end
+#
+#     RSpec.describe GenericFleeb, type: :fleeb do
+#       it { is_expected.to be_conjugated_from Foo }
+#     end
+
+RSpec::Matchers.define :be_conjugated_from do |conjunctive|
+  match { expect(conjunctive.conjugate(test_subject)).to eq test_subject }
+  description { "be conjugated from #{conjunctive}" }
+  failure_message { "expected #{test_subject} to be conjugated from #{conjunctive} but wasn't" }
+
+  def test_subject
+    subject.is_a?(Class) ? subject : subject.class
+  end
+end

data/lib/conjunction/rspec/custom_matchers/conjugate_into.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# RSpec matcher that tests usage of `.conjoins`
+#
+#     class Foo < ApplicationRecord
+#     end
+#
+#     class FooFleeb < ApplicationFleeb; end
+#
+#     RSpec.describe Foo, type: :model do
+#       it { is_expected.to conjugate_into FooFleeb }
+#     end
+
+RSpec::Matchers.define :conjugate_into do |junction|
+  match { |subject| expect(subject.conjugate(junction)).to eq junction }
+  description { "conjugate into #{junction}" }
+  failure_message { |subject| "expected #{subject} to conjugate into #{junction} but didn't" }
+end

data/lib/conjunction/rspec/custom_matchers/define_prototype.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# RSpec matcher that tests the presence of `.prototype`
+#
+#     class ApplicationFleeb
+#       include Conjunction::Junction
+#
+#       prefixed_with "Fleeb"
+#     end
+#
+#     class GenericFleeb < ApplicationFleeb; end
+#
+#     RSpec.describe GenericFleeb, type: :fleeb do
+#       it { is_expected.not_to define_prototype }
+#     end
+
+RSpec::Matchers.define :define_prototype do
+  match { |subject| expect(subject.prototype).not_to be_nil }
+  description { "define prototype" }
+  failure_message { |subject| "expected #{subject} to define prototype but didn't" }
+end

data/lib/conjunction/rspec/custom_matchers/have_conjunction_prefix.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# RSpec matcher that tests usage of `.prefixed_with`
+#
+#     class ApplicationGrodus
+#       include Conjunction::Junction
+#
+#       prefixed_with "Grodus::"
+#     end
+#
+#     class Grodus::Example < ApplicationGrodus; end
+#
+#     RSpec.describe Grodus::Example, type: :grodus do
+#       it { is_expected.to have_conjunction_prefix "Grodus::" }
+#     end
+
+RSpec::Matchers.define :have_conjunction_prefix do |prefix|
+  match { |subject| expect(subject.conjunction_prefix).to eq prefix }
+  description { "have conjunction prefix `#{prefix}'" }
+  failure_message do |subject|
+    "expected #{subject} to have conjunction prefix `#{prefix}' but had `#{subject.conjunction_prefix}'"
+  end
+end

data/lib/conjunction/rspec/custom_matchers/have_conjunction_suffix.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# RSpec matcher that tests usage of `.suffixed_with`
+#
+#     class ApplicationLaw < Law::LawBase
+#       include Conjunction::Junction
+#
+#       suffixed_with "Law"
+#     end
+#
+#     RSpec.describe ApplicationLaw, type: :law do
+#       it { is_expected.to have_conjunction_suffix "Law" }
+#     end
+
+RSpec::Matchers.define :have_conjunction_suffix do |suffix|
+  match { |subject| expect(subject.conjunction_suffix).to eq suffix }
+  description { "have conjunction suffix `#{suffix}'" }
+  failure_message do |subject|
+    "expected #{subject} to have conjunction suffix `#{suffix}' but had `#{subject.conjunction_prefix}'"
+  end
+end

data/lib/conjunction/rspec/custom_matchers/have_junction_key.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# RSpec matcher that tests usage of `.suffixed_with`
+#
+#     class ApplicationDingleBop
+#       include Conjunction::Junction
+#
+#       suffixed_with "DingleBop"
+#     end
+#
+#     RSpec.describe ApplicationDingleBop, type: :dingle_bop do
+#       it { is_expected.to have_junction_key :dingle_bop }
+#     end
+
+RSpec::Matchers.define :have_junction_key do |key|
+  match { |subject| expect(subject.junction_key).to eq key }
+  description { "have junction key `#{key}'" }
+  failure_message do |subject|
+    "expected #{subject} to have junction key `#{key}' but had `#{subject.junction_key}'"
+  end
+end

data/lib/conjunction/rspec/custom_matchers/have_prototype.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# RSpec matcher that tests the value of `.prototype`
+#
+#     class ApplicationFleeb < ActiveRecord::Base
+#       include Conjunction::Junction
+#
+#       prefixed_with "Fleeb"
+#     end
+#
+#     class FooFleeb < ApplicationFleeb; end
+#
+#     RSpec.describe FooFleeb, type: :fleeb do
+#       it { is_expected.to have_prototype Foo }
+#     end
+
+RSpec::Matchers.define :have_prototype do |prototype|
+  match { |subject| expect(subject.prototype).to eq prototype }
+  description { "have prototype name `#{prototype}'" }
+  failure_message { |subject| "expected #{subject} to have prototype `#{prototype}' but had `#{subject.prototype}'" }
+end

data/lib/conjunction/rspec/custom_matchers/have_prototype_name.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# RSpec matcher that tests the value of `.prototype_name`
+#
+#     class ApplicationRecord < ActiveRecord::Base
+#       include Conjunction::Conjunctive
+#     end
+#
+#     class ShippingAddress < ApplicationRecord; end
+#
+#     RSpec.describe ShippingAddress, type: :model do
+#       it { is_expected.to have_prototype_name "ShippingAddress" }
+#     end
+
+RSpec::Matchers.define :have_prototype_name do |prototype_name|
+  match { |subject| expect(subject.prototype_name).to eq prototype_name }
+  description { "have prototype name `#{prototype_name}'" }
+  failure_message do |subject|
+    "expected #{subject} to have prototype name `#{prototype_name}' but had `#{subject.prototype_name}'"
+  end
+end

data/lib/conjunction/rspec/custom_matchers.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "custom_matchers/be_conjoined_to"
+require_relative "custom_matchers/be_conjugated_from"
+require_relative "custom_matchers/conjugate_into"
+require_relative "custom_matchers/define_prototype"
+require_relative "custom_matchers/have_conjunction_prefix"
+require_relative "custom_matchers/have_conjunction_suffix"
+require_relative "custom_matchers/have_junction_key"
+require_relative "custom_matchers/have_prototype"
+require_relative "custom_matchers/have_prototype_name"

data/lib/conjunction/spec_helper.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "rspec/custom_matchers"

data/lib/conjunction/version.rb

@@ -2,5 +2,5 @@
 
 module Conjunction
   # This constant is managed by spicerack
-  VERSION = "0.20.2"
+  VERSION = "0.21.0"
 end

data/lib/conjunction.rb

@@ -1,6 +1,24 @@
 # frozen_string_literal: true
 
+require "active_support"
+
+require "spicerack"
+
 require "conjunction/version"
 
+require "conjunction/configuration"
+
+require "conjunction/nexus"
+
+require "conjunction/prototype"
+require "conjunction/conjunctive"
+require "conjunction/naming_convention"
+require "conjunction/junction"
+
 module Conjunction
+  include Spicerack::Configurable::ConfigDelegation
+  delegates_to_configuration
+
+  class Error < StandardError; end
+  class DisjointedError < Error; end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: conjunction
 version: !ruby/object:Gem::Version
-  version: 0.20.2
+  version: 0.21.0
 platform: ruby
 authors:
 - Eric Garside
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-06 00:00:00.000000000 Z
+date: 2020-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -24,6 +24,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 5.2.1
+- !ruby/object:Gem::Dependency
+  name: spicerack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.1
 description: Join together related concepts for a common purpose with Conjugation
 email:
 - garside@gmail.com
@@ -35,6 +63,23 @@ files:
 - LICENSE.txt
 - README.md
 - lib/conjunction.rb
+- lib/conjunction/configuration.rb
+- lib/conjunction/conjunctive.rb
+- lib/conjunction/junction.rb
+- lib/conjunction/naming_convention.rb
+- lib/conjunction/nexus.rb
+- lib/conjunction/prototype.rb
+- lib/conjunction/rspec/custom_matchers.rb
+- lib/conjunction/rspec/custom_matchers/be_conjoined_to.rb
+- lib/conjunction/rspec/custom_matchers/be_conjugated_from.rb
+- lib/conjunction/rspec/custom_matchers/conjugate_into.rb
+- lib/conjunction/rspec/custom_matchers/define_prototype.rb
+- lib/conjunction/rspec/custom_matchers/have_conjunction_prefix.rb
+- lib/conjunction/rspec/custom_matchers/have_conjunction_suffix.rb
+- lib/conjunction/rspec/custom_matchers/have_junction_key.rb
+- lib/conjunction/rspec/custom_matchers/have_prototype.rb
+- lib/conjunction/rspec/custom_matchers/have_prototype_name.rb
+- lib/conjunction/spec_helper.rb
 - lib/conjunction/version.rb
 homepage: https://github.com/Freshly/spicerack/tree/master/conjunction
 licenses:
@@ -43,7 +88,7 @@ metadata:
   homepage_uri: https://github.com/Freshly/spicerack/tree/master/conjunction
   source_code_uri: https://github.com/Freshly/spicerack/tree/master/conjunction
   changelog_uri: https://github.com/Freshly/spicerack/blob/master/conjunction/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/conjunction/0.20.2
+  documentation_uri: https://www.rubydoc.info/gems/conjunction/0.21.0
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -59,7 +104,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubyforge_project: 
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Provides a mechanism to loosely coupled a suite of cross-referenced objects