nobrainer-references 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65580cce199dbbd155e48df8d0a7bbd3639829306b9b5ff6928030210cd37720
+  data.tar.gz: f1d9e1bde0a355826be32ad48dcccce95cdc236439f71d034b15e49822a7489c
+SHA512:
+  metadata.gz: f38850e024055580bbad17616b9348e5c473ab4198b5f4e0aaacab94b2bb6a978fa74705067d81fb2546b70ebdb78c8747fea39f66376786d90a3ebff6b3bb56
+  data.tar.gz: 97bd8654f56171de5ad971b2fc302814efe68fcd5822f4c049b0594504f2eb362f99ed10f727abc2fef89e79ba3aa3eaa1d0cb248deac6533c0cbae2ec779731

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-2024 Steve Sloan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,72 @@
+# NoBrainer References
+
+An alternative to ActiveRecord-style associations using idiomatic Ruby.
+
+## Design
+
+ActiveRecord provides _associations_ between models as a convenient interface to SQL's use of _relations_ between table rows, and NoBrainer matches this functionality.  But they are fundamentally different to the way that Ruby and most programming languages store relationships between models: _references_.
+
+## Installation
+
+Add the Ruby gem to your Gemfile:
+
+    $ bundle add nobrainer-references
+
+## Example
+
+    class Publisher
+      include NoBrainer::Document
+      field :name, type: String
+    end
+
+    class Person
+      include NoBrainer::Document
+      field :name, type: String
+    end
+
+    class Book
+      include NoBrainer::Document
+      field :title, type: String
+      references_many :authors, model: Person
+      references_one  :publisher
+    end
+
+    douglas_adams = Person.create!(name: "Douglas Adams")
+    john_lloyd = Person.create!(name: "John Lloyd")
+    publisher = Publisher.create!(name: "Pan Books")
+    book = Book.create!(
+      title: "The Meaning of Liff",
+      authors: [douglas_adams, john_lloyd],
+      publisher: publisher
+    )
+
+    ...
+
+    book = Book.where(title: "The Meaning of Liff").first
+    book.publisher.name         #=> "Pan Books"
+    book.authors.map(&:name)    #=> [ "Douglas Adams", "John Lloyd" ]
+
+## How It Works
+
+This gem adds a NoBrainer field type that's a `Reference` to a model of a particular type.  This type acts as a lazy-loading _delegator_, which serializes the referred object by its `id` when saving the model, and then later loads that object when it's dereferenced (or is eager-loaded).
+
+`references_one` and `references_many` are convenience methods for creating fields with the correct types and default names according to convention: 
+
+    references_one  :publisher
+    # ... same as ...
+    field :publisher, type: Reference.to(Publisher), store_as: 'publishder_id'
+
+    references_many :authors, model: Person
+    # ... same as ...
+    field :authors, type: Array.of(Reference.to(Person)), store_as: 'author_ids'
+
+It also supports eager-loading of references:
+
+    book = Book.eager_load(:authors, :publisher).where(title: "The Meaning of Liff").first
+    book.authors(&:map)   #=> [ "Douglas Adams", "John Lloyd" ]
+
+## Future Plans
+
+* Add a `referenced_by` convenience method for tracking which other models/fields reference this one.  Provides parity with the ActiveRecord `belongs_to`/`has_many` inverse associations.  This would be installed automatically by the `references_one` and `references_many` convenience methods.
+
+* Use reference tracking to implement garbage collection.

data/lib/no_brainer/document/references.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'active_support/dependencies/autoload'
+require 'active_support/concern'
+
+require 'no_brainer/types/reference'
+require 'no_brainer/references/eager_loader'
+
+module NoBrainer
+  module Document
+    module References
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def references_one(name, model: nil, store_as: nil, inverse: nil, **opts)
+          name = name.to_s
+          store_as ||= "#{name}_id"
+          model ||= name.classify.constantize
+          if model.is_a?(String)
+            name = model
+            model = ->{ const_get(name) }
+          end
+
+          field name.to_sym, type: Reference.to(model), store_as: store_as, **opts
+        end
+
+        def references_many(name, model: nil, store_as: nil, inverse: nil, **opts)
+          name = name.to_s
+          store_as ||= "#{name.singularize}_ids"
+          model ||= name.singularize.classify.constantize
+          if model.is_a?(String)
+            name = model
+            model = ->{ const_get(name) }
+          end
+
+          field name.to_sym, type: Array.of(Reference.to(model)), store_as: store_as, **opts
+        end
+      end
+    end
+  end
+end

data/lib/no_brainer/references/eager_loader.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'no_brainer/document/association/eager_loader'
+
+module NoBrainer::Document::References
+  # adapted from NoBrainer::Document::Association::EagerLoader
+  def self.eager_load(docs, field_name, field=nil, criteria=nil)
+    return  if docs.blank?
+
+    field_name = field_name.to_sym
+    field ||= docs.first.root_class.fields[field_name]
+    ref_type = field_type = field[:type]
+    if (field_type <= Array) && field_type.respond_to?(:object_type) && (field_type.object_type <= NoBrainer::Reference)
+      ref_type = field_type.object_type
+    end
+    raise TypeError, "#{ref_type} is not a NoBrainer::Reference"  unless ref_type <= NoBrainer::Reference
+    model_type = ref_type.model_type
+
+    refs = docs.flat_map { |doc|  doc.read_attribute(field_name) }
+    refs.compact!
+    refs.reject!(&:__hasobj__)
+
+    if refs.present?
+      target_key = model_type.table_config.primary_key.to_sym
+      ref_ids = refs.map(&:id).uniq
+
+      query = model_type.without_ordering
+      query = query.merge(criteria)  if criteria
+      targets = query.where(target_key.in => ref_ids).group_by(&target_key)
+      refs.each do |ref|
+        if (target = targets[ref.id]&.first)
+          ref.__setobj__(target)
+        end
+      end
+      refs.uniq!
+    end
+
+    docs.select { |doc| Array(doc.read_attribute(field_name)).all?(&:__hasobj__) }
+  end
+
+  module AssociationExt
+    def eager_load_association(docs, association_name, criteria=nil)
+      if (field = docs&.first) && (field = field.root_class.fields[association_name.to_sym]) && field_is_reference_type?(field)
+        NoBrainer::Document::References.eager_load(docs, association_name, field, criteria)
+      else
+        super
+      end
+    end
+
+  private
+
+    def field_is_reference_type?(field)
+      field && (type = field[:type]) && (
+        (type <= NoBrainer::Reference) ||
+        (type <= Array && type.respond_to?(:object_type) && (type.object_type <= NoBrainer::Reference))
+      )
+    end
+
+    NoBrainer::Document::Association::EagerLoader.extend(self)
+  end
+end

data/lib/no_brainer/references/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module NoBrainer
+  module References
+    VERSION = '1.0.0'.freeze
+  end
+end

data/lib/no_brainer/types/reference.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'no_brainer/document'
+
+module NoBrainer
+  class Reference < SimpleDelegator
+    mattr_accessor :autosave
+    self.autosave = true
+
+    def self.to(model_type = nil, &model_type_proc)
+      raise ArgumentError, "wrong number of arguments (given 2, expect 1)"  if model_type && model_type_proc
+      raise ArgumentError, "wrong number of arguments (given 0, expect 1)"  unless model_type || model_type_proc
+      if model_type.respond_to?(:call)
+        model_type_proc = model_type
+        model_type = nil
+      end
+
+      if model_type.const_defined?('Reference', !:inherited)
+        return model_type.const_get('Reference', !:inherited)
+      end
+
+      ref_type = if model_type
+        model_type = resolve_model_type(model_type)
+        ::Class.new(Reference) { define_singleton_method(:model_type) { model_type } }
+      else
+        # lazy-load model class
+        ::Class.new(Reference) { define_singleton_method(:model_type) { @model_type ||= resolve_model_type(model_type_proc) } }
+      end
+      model_type.const_set('Reference', ref_type)
+    end
+
+    def self.resolve_model_type(type)
+      type = type.call  if type.respond_to?(:call)
+      if type.const_defined?('Reference', !:inherited)
+        return type.const_get('Reference', !:inherited)
+      end
+      unless type < Document
+        raise TypeError, "Expected Document subclass, got #{type.inspect}"
+      end
+      type
+    end
+    private_class_method :resolve_model_type
+
+    def self.name
+      str = "Reference"
+      str += "(#{model_type.name})"  if respond_to?(:model_type)
+      str
+    end
+
+    attr_reader :id
+
+    def initialize(id, object = nil)
+      @id = id
+      __setobj__(object)  unless object.nil?
+    end
+
+    def inspect
+      "#<*#{self.class.model_type} " + (
+        __hasobj__ ? __getobj__.inspectable_attributes.map { |k,v| "#{k}: #{v.inspect}" }.join(', ')
+                   : "#{self.class.model_type.table_config.primary_key}: #{id.inspect}"
+      ) +  ">"
+    end
+
+    def dup
+      self.class.new(@id)
+    end
+    alias_method :deep_dup, :dup
+
+    def __getobj__
+      super do
+        if @missing
+          nil
+        elsif @id
+          model = self.class.model_type
+          unless (obj = model.find?(@id))
+            @missing = true
+            raise NoBrainer::Error::MissingAttribute, "#{model} :#{model.pk_name}=>#{@id.inspect} not found"
+          end
+          __setobj__(obj)
+        elsif block_given?
+          yield
+        end
+      end
+    end
+
+    def __hasobj__
+      defined? @delegate_sd_obj
+    end
+
+    def self.nobrainer_cast_user_to_model(value)
+      case value
+        when Reference
+          unless value.class.model_type == model_type
+            raise NoBrainer::Error::InvalidType, "Expected Reference to #{model_type}, got #{value}"
+          end
+          value
+        when model_type
+          new(value.id, value)
+        when nil
+          nil
+        else
+          raise NoBrainer::Error::InvalidType
+      end
+    end
+
+    def self.nobrainer_cast_model_to_db(value)
+      value&.save!  if value&.new_record? && self.autosave
+      value&.id
+    end
+
+    def self.nobrainer_cast_db_to_model(value)
+      value && new(value)
+    end
+  end
+
+  Document::Types::Reference = Reference
+end

data/lib/nobrainer-references.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'active_support/dependencies/autoload'
+require 'nobrainer'
+require 'no_brainer/document/references'
+
+module NoBrainer
+  autoload :Array, :Reference
+
+  module Document
+    include References
+  end
+end

data/spec/integration/eager_loader_spec.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe NoBrainer::Document::References do
+  before(:all) do
+    class Person
+      include NoBrainer::Document
+      field :name, type: String
+    end
+
+    class Post
+      include NoBrainer::Document
+      field :title, type: String
+      field :authors, type: Array.of(Reference.to(Person))
+      field :publisher, type: Reference.to(Person)
+    end
+  end
+
+  it "eager loads single reference" do
+    publisher = Person.create!(name: Faker::Name.name)
+    post = Post.create!(title: Faker::Name.name, publisher: publisher)
+
+    post = Post.where(title: post.title).eager_load(:publisher).first
+    expect(Person).not_to receive(:find)
+    expect(post.publisher.name).to eq publisher.name
+  end
+
+  it "eager loads reference array" do
+    bob, doug = Person.create!(name: "Bob"), Person.create!(name: "Doug")
+    post = Post.create!(title: Faker::Name.name, authors: [bob, doug])
+
+    post = Post.where(title: post.title).eager_load(:authors).first
+    expect(Person).not_to receive(:find)
+    expect(post.authors.map(&:name)).to eq [bob, doug].map(&:name)
+  end
+end

data/spec/integration/reference_spec.rb

@@ -0,0 +1,57 @@
+require 'spec_helper'
+
+RSpec.describe NoBrainer::Reference do
+  before(:all) do
+    class Person
+      include NoBrainer::Document
+      field :name, type: String
+    end
+
+    class Post
+      include NoBrainer::Document
+      field :title,     type: String
+      field :authors,   type: Array.of(Reference.to(Person))
+      field :publisher, type: Reference.to(Person)
+      index :authors, multi: true
+      index :publisher
+    end
+
+    NoBrainer.sync_schema
+  end
+
+  it "references one" do
+    publisher = Person.create!(name: "Marvin")
+    post = Post.create!(title: "Stuff", publisher: publisher)
+
+    post.reload
+    expect(post.publisher.name).to eq publisher.name
+    expect(Post.where(publisher: publisher)).to eq [post]
+  end
+
+  it "references many" do
+    bob, doug = Person.create!(name: "Bob"), Person.create!(name: "Doug")
+    bob_post = Post.create!(title: "Bob Stuff", authors: bob).reload
+    doug_post = Post.create!(title: "Doug Stuff", authors: doug).reload
+    bd_post = Post.create!(title: "Body & Doug Stuff", authors: [bob, doug]).reload
+    db_post = Post.create!(title: "Doug & Bob Stuff", authors: [doug, bob]).reload
+
+    expect(Post.where(:authors.any => bob)).to eq [bob_post, bd_post, db_post]
+    expect(Post.where(:authors.any => doug)).to eq [doug_post, bd_post, db_post]
+    expect(Post.where(:authors.any.in => [bob, doug])).to eq [bob_post, doug_post, bd_post, db_post]
+  end
+
+  it "exception when referenced item is missing" do
+    publisher = Person.create!(name: "Marvin")
+    post = Post.create!(title: "Stuff", publisher: publisher)
+
+    expect(post.publisher).to eq publisher
+    publisher.delete
+    post.reload
+    expect {
+      post.publisher
+    }.to raise_error(NoBrainer::Error::MissingAttribute)
+
+    post.publisher = nil
+    post.save!
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+require 'rubygems'
+require 'bundler'
+Bundler.require(:default, :test)
+
+SPEC_ROOT = File.expand_path File.dirname(__FILE__)
+Dir["#{SPEC_ROOT}/support/**/*.rb"].each { |f| require f unless File.basename(f) =~ /^_/ }
+
+RSpec.configure do |config|
+  config.order = :random
+  config.color = true
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+
+  if ENV['TRACE']
+    config.before do
+      $trace_file = File.open(ENV['TRACE'], 'w')
+      TracePoint.new(:call, :raise) do |tp|
+        $trace_file.puts "#{tp.event} #{tp.path} #{tp.method_id}:#{tp.lineno}"
+      end.enable
+    end
+  end
+end

data/spec/support/auto_remove_const_in_rspec.rb

@@ -0,0 +1,12 @@
+RSpec.configure do |config|
+  config.around(:example, remove_const: true) do |example|
+    const_before = Object.constants
+
+    example.run
+
+    const_after = Object.constants
+    (const_after - const_before).each do |const|
+      Object.send(:remove_const, const)
+    end
+  end
+end

data/spec/support/factory_bot.rb

@@ -0,0 +1,8 @@
+require 'factory_bot'
+
+RSpec.configure do |config|
+  config.include FactoryBot::Syntax::Methods
+  config.before(:suite) do
+    FactoryBot.find_definitions
+  end
+end

data/spec/support/nobrainer.rb

@@ -0,0 +1,15 @@
+RSpec.configure do |config|
+  config.before(:suite) do
+    NoBrainer.sync_schema
+    NoBrainer.purge!
+  end
+
+  config.after(:suite) do
+    NoBrainer.drop!
+  end
+end
+
+NoBrainer.configure do |config|
+  config.app_name = 'nobrainer_refs'
+  config.environment = :test
+  end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: nobrainer-references
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Steve Sloan
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-12-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nobrainer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.44'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.44'
+description: ''
+email: steve@finagle.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/no_brainer/document/references.rb
+- lib/no_brainer/references/eager_loader.rb
+- lib/no_brainer/references/version.rb
+- lib/no_brainer/types/reference.rb
+- lib/nobrainer-references.rb
+- spec/integration/eager_loader_spec.rb
+- spec/integration/reference_spec.rb
+- spec/spec_helper.rb
+- spec/support/auto_remove_const_in_rspec.rb
+- spec/support/factory_bot.rb
+- spec/support/nobrainer.rb
+homepage: https://github.com/CodeMonkeySteve/nobrainer-references
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 3
+summary: NoBrainer support for model references
+test_files:
+- spec/integration/eager_loader_spec.rb
+- spec/integration/reference_spec.rb
+- spec/spec_helper.rb
+- spec/support/auto_remove_const_in_rspec.rb
+- spec/support/factory_bot.rb
+- spec/support/nobrainer.rb