terrestrial 0.1.0 → 0.1.1

data/spec/persistence_efficiency_spec.rb

@@ -0,0 +1,224 @@
+require "spec_helper"
+
+require "support/mapper_setup"
+require "support/sequel_persistence_setup"
+require "support/seed_data_setup"
+require "terrestrial"
+
+RSpec.describe "Graph persistence efficiency" do
+  include_context "mapper setup"
+  include_context "sequel persistence setup"
+  include_context "seed data setup"
+
+  let(:mapper) { user_mapper }
+  let(:user_query) { mapper.where(id: "users/1") }
+  let(:user) { user_query.first }
+
+  context "when modifying the root node" do
+    let(:modified_email) { "modified@example.com" }
+
+    context "and only the root node" do
+      before do
+        user.email = modified_email
+      end
+
+      it "performs 1 update" do
+        expect {
+          mapper.save(user)
+        }.to change { query_counter.update_count }.by(1)
+      end
+
+      it "sends only the updated fields to the datastore" do
+        mapper.save(user)
+        update_sql = query_counter.updates.last
+
+        expect(update_sql).to eq(
+          %{UPDATE "users" SET "email" = '#{modified_email}' WHERE ("id" = '#{user.id}')}
+        )
+      end
+    end
+  end
+
+  context "when modifying a directly associated (has many) object" do
+    let(:modified_post_subject) { "modified post subject" }
+
+    before do
+      user.posts.first.subject = modified_post_subject
+    end
+
+    it "performs 1 update" do
+      expect {
+        mapper.save(user)
+      }.to change { query_counter.update_count }.by(1)
+    end
+
+    it "performs 0 deletes" do
+      expect {
+        mapper.save(user)
+      }.to change { query_counter.delete_count }.by(0)
+    end
+
+    it "performs 0 additional reads" do
+      expect {
+        mapper.save(user)
+      }.to change { query_counter.read_count }.by(0)
+    end
+  end
+
+  context "when loading many nodes of the graph" do
+    let(:post) {
+      user.posts.first
+    }
+
+    context "and modifying an intermediate node" do
+      before do
+        post.subject = "MODIFIED"
+      end
+
+      it "performs 1 write" do
+        expect {
+          mapper.save(user)
+        }.to change { query_counter.update_count }.by(1)
+      end
+    end
+
+    context "and modifying a leaf node" do
+      let(:comment) { post.comments.first }
+
+      before do
+        comment.body = "UPDATED!"
+      end
+
+      it "performs 1 update" do
+        expect {
+          mapper.save(user)
+        }.to change { query_counter.update_count }.by(1)
+      end
+    end
+
+    context "and modifying both a leaf and intermediate node" do
+      let(:comment) { post.comments.first }
+
+      before do
+        comment.body = "UPDATED!"
+        post.subject = "MODIFIED"
+      end
+
+      it "performs 2 updates" do
+        expect {
+          mapper.save(user)
+        }.to change { query_counter.update_count }.by(2)
+      end
+    end
+  end
+
+  context "when modifying a many to many association" do
+    let(:post) { user.posts.first }
+    let(:category) { post.categories.first }
+
+    before do
+      category.name = "UPDATED"
+    end
+
+    it "performs 1 write" do
+        expect {
+          mapper.save(user)
+        }.to change { query_counter.update_count }.by(1)
+    end
+  end
+
+  context "eager loading" do
+    context "on root node" do
+      it "performs 1 read per table rather than n + 1" do
+        expect {
+          mapper.eager_load(:posts => []).all.map { |user|
+            [user.id, user.posts.map(&:id)]
+          }
+        }.to change { query_counter.read_count }.by(2)
+      end
+    end
+
+    context "with nested has many" do
+      it "performs 1 read per table rather than n + 1" do
+        expect {
+          user_query
+            .eager_load(:posts => { :comments => [] })
+            .first
+            .posts
+            .map { |post| post.comments.map(&:id) }
+        }.to change { query_counter.read_count }.by(3)
+      end
+    end
+
+    context "with has many and belongs to" do
+      it "performs 1 read per table rather than n + 1" do
+        expect {
+          user_query
+            .eager_load(:posts => { :comments => { :commenter => [] }})
+            .flat_map(&:posts)
+            .flat_map(&:comments)
+            .flat_map(&:commenter)
+        }.to change { query_counter.read_count }.by(4)
+      end
+    end
+
+    context "for has many to has many through" do
+      it "performs 1 read per table (including join table) rather than n + 1" do
+        expect {
+          user_query
+            .eager_load(:posts => { :categories => [] })
+            .flat_map(&:posts)
+            .flat_map(&:categories)
+            .flat_map(&:id)
+        }.to change { query_counter.read_count }.by(4)
+      end
+    end
+
+    context "for has many through to has many" do
+      it "performs 1 read per table (includiing join table) rather than n + 1" do
+        expect {
+          user_query
+            .eager_load(:posts => { :categories => { :posts => [] }})
+            .flat_map(&:posts)
+            .flat_map(&:categories)
+            .flat_map(&:posts)
+        }.to change { query_counter.read_count }.by(6)
+      end
+    end
+
+    context "eager load multiple associations at same level" do
+      it "performs 1 read per table (includiing join table) rather than n + 1" do
+        expect {
+          posts = user_query
+            .eager_load(:posts => { :comments => {}, :categories => {} })
+            .flat_map(&:posts)
+
+          categories = posts.flat_map(&:categories)
+          comments = posts.flat_map(&:comments)
+        }.to change { query_counter.read_count }.by(5)
+      end
+    end
+
+    context "mixed eager and lazy loading" do
+      it "lazy data can still be loaded while eager data remains efficient" do
+        eager_queries = 6
+        lazy_comment_queries = 3
+
+        expect {
+          user_query
+            .eager_load(:posts => { :categories => { :posts => [] }})
+            .flat_map(&:posts)
+            .flat_map(&:categories)
+            .flat_map(&:posts)
+            .flat_map(&:comments)
+        }.to change {
+          query_counter.read_count
+        }.by(eager_queries + lazy_comment_queries)
+      end
+    end
+  end
+
+  after do |example|
+    query_counter.show_queries if example.exception
+  end
+end

data/spec/predefined_queries_spec.rb

@@ -0,0 +1,62 @@
+require "spec_helper"
+
+require "support/mapper_setup"
+require "support/sequel_persistence_setup"
+require "support/seed_data_setup"
+require "terrestrial"
+require "terrestrial/configurations/conventional_configuration"
+
+RSpec.describe "Predefined subset queries" do
+  include_context "mapper setup"
+  include_context "sequel persistence setup"
+  include_context "seed data setup"
+
+  subject(:users) { user_mapper }
+
+  context "on the top level mapper" do
+    context "subset is defined with a block" do
+      before do
+        configs.fetch(:users).merge!(
+          subsets: {
+            tricketts: ->(dataset) {
+              dataset
+                .where(last_name: "Trickett")
+                .order(:first_name)
+            },
+          },
+        )
+      end
+
+      it "maps the result of the subset" do
+        expect(users.subset(:tricketts).map(&:first_name)).to eq([
+          "Hansel",
+          "Jasper",
+        ])
+      end
+    end
+  end
+
+  context "on a has many association" do
+    before do
+      configs.fetch(:posts).merge!(
+        subsets: {
+          body_contains: ->(dataset, search_string) {
+            dataset.where("body like '%#{search_string}%'")
+          },
+        },
+      )
+    end
+
+    let(:user) { users.first }
+
+    it "maps the datastore subset" do
+      expect(user.posts.subset(:body_contains, "purrr").map(&:id))
+        .to eq(["posts/2"])
+    end
+
+    it "returns an immutable collection" do
+      expect(user.posts.subset(:body_contains, "purrr").public_methods)
+        .not_to include(:push, :<<, :delete)
+    end
+  end
+end

data/spec/proxying_spec.rb

@@ -0,0 +1,88 @@
+require "spec_helper"
+
+require "support/mapper_setup"
+require "support/sequel_persistence_setup"
+require "support/seed_data_setup"
+require "terrestrial"
+
+RSpec.describe "Proxying associations" do
+  include_context "mapper setup"
+  include_context "sequel persistence setup"
+  include_context "seed data setup"
+
+  context "of type `has_many`" do
+    subject(:mapper) { user_mapper }
+
+    let(:user) {
+      mapper.where(id: "users/1").first
+    }
+
+    let(:posts) { user.posts }
+
+    describe "limiting datastore reads" do
+      context "when loading the root node" do
+        it "only performs one read" do
+          expect {
+            user
+          }.to change { query_counter.read_count }.by(1)
+        end
+      end
+
+      context "when getting a reference to an association proxy" do
+        before { user }
+
+        it "does no additional reads" do
+          expect{
+            user.posts
+          }.to change { query_counter.read_count }.by(0)
+        end
+      end
+
+      context "when iteratiing over a has many association" do
+        before { posts }
+
+        it "does a single additional read for the association collection" do
+          expect {
+            user.posts.each { |x| x }
+          }.to change { query_counter.read_count }.by(1)
+        end
+
+        context "when doing this more than once" do
+          before do
+            posts.each { |x| x }
+          end
+
+          it "performs no additional reads" do
+            expect {
+              user.posts.each { |x| x }
+            }.not_to change { query_counter.read_count }
+          end
+        end
+      end
+
+      context "when getting a reference to a many to many association" do
+        before { post }
+
+        let(:post) { user.posts.first }
+
+        it "does no additional reads" do
+          expect {
+            post.categories
+          }.to change { query_counter.read_count }.by(0)
+        end
+      end
+
+      context "when iterating over a many to many association" do
+        let(:category_count) { 3 }
+
+        it "does 1 read" do
+          post = user.posts.first
+
+          expect {
+            post.categories.each { |x| x }
+          }.to change { query_counter.read_count }.by(1)
+        end
+      end
+    end
+  end
+end

data/spec/querying_spec.rb

@@ -0,0 +1,48 @@
+require "spec_helper"
+
+require "support/mapper_setup"
+require "support/sequel_persistence_setup"
+require "support/seed_data_setup"
+require "terrestrial"
+
+RSpec.describe "Querying" do
+  include_context "mapper setup"
+  include_context "sequel persistence setup"
+  include_context "seed data setup"
+
+  subject(:mapper) { user_mapper }
+
+  let(:user) {
+    mapper.where(id: "users/1").first
+  }
+
+  let(:query_criteria) {
+    {
+      body: "I do it three times purrr day",
+    }
+  }
+
+  let(:filtered_posts) {
+    user.posts.where(query_criteria)
+  }
+
+  describe "arbitrary where query" do
+    it "returns a filtered version of the association" do
+      expect(filtered_posts.map(&:id)).to eq(["posts/2"])
+    end
+
+    it "delegates the query to the datastore, performs two additiona reads" do
+      expect {
+        filtered_posts.map(&:id)
+      }.to change { query_counter.read_count }.by(2)
+    end
+
+    it "returns another collection" do
+      expect(filtered_posts).not_to be(user.posts)
+    end
+
+    it "returns an immutable collection" do
+      expect(filtered_posts.public_methods).not_to include(:push, :<<, :delete)
+    end
+  end
+end

data/spec/readme_examples_spec.rb

@@ -0,0 +1,35 @@
+require "spec_helper"
+
+require "support/mapper_setup"
+require "support/sequel_persistence_setup"
+require "support/seed_data_setup"
+require "terrestrial"
+
+require "spec_helper"
+
+require "support/mapper_setup"
+require "support/sequel_persistence_setup"
+require "support/seed_data_setup"
+require "terrestrial"
+
+RSpec.describe "README examples" do
+  include_context "sequel persistence setup"
+
+  readme_contents = File.read("README.md")
+
+  code_samples = readme_contents
+    .split("```ruby")
+    .drop(1)
+    .map { |s| s.split("```").first }
+
+  code_samples.each_with_index do |code_sample, i|
+    it "executes without error" do
+      begin
+        Module.new.module_eval(code_sample)
+      rescue => e
+        File.open("./example#{i}.rb", "w") { |f| f.puts(code_sample) }
+        binding.pry if ENV["DEBUG"]
+      end
+    end
+  end
+end

data/spec/sequel_mapper/abstract_record_spec.rb

@@ -0,0 +1,244 @@
+require "spec_helper"
+
+require "terrestrial/abstract_record"
+
+RSpec.describe Terrestrial::AbstractRecord do
+  subject(:record) {
+    Terrestrial::AbstractRecord.new(
+      namespace,
+      primary_key_fields,
+      raw_data,
+      depth,
+    )
+  }
+
+  let(:namespace) { double(:namespace) }
+  let(:primary_key_fields) { [ :id1, :id2 ] }
+  let(:depth) { 0 }
+
+  let(:raw_data) {
+    {
+      id1: id1,
+      id2: id2,
+      name: name,
+    }
+  }
+
+  let(:id1) { double(:id1) }
+  let(:id2) { double(:id2) }
+  let(:name) { double(:name) }
+
+  describe "#namespace" do
+    it "returns the namespace" do
+      expect(record.namespace).to eq(namespace)
+    end
+  end
+
+  describe "#identity" do
+    it "returns the primary key fields" do
+      expect(record.identity).to eq(
+        id1: id1,
+        id2: id2,
+      )
+    end
+  end
+
+  describe "#fetch" do
+    it "delegates to the underlying Hash representation" do
+      expect(record.fetch(:id1)).to eq(id1)
+      expect(record.fetch(:name)).to eq(name)
+      expect(record.fetch(:not_there, "nope")).to eq("nope")
+      expect(record.fetch(:not_there) { "lord no" }).to eq("lord no")
+    end
+  end
+
+  describe "#to_h" do
+    it "returns a raw_data merged with identity" do
+      expect(record.to_h).to eq(
+        id1: id1,
+        id2: id2,
+        name: name,
+      )
+    end
+  end
+
+  describe "#if_upsert" do
+    it "returns self" do
+      expect(
+        record.if_upsert { |_| }
+      ).to be(record)
+    end
+
+    it "does not call the block" do
+      expect {
+        record.if_upsert { |_| raise "Does not happen" }
+      }.not_to raise_error
+    end
+  end
+
+  describe "#if_delete" do
+    it "returns self" do
+      expect(
+        record.if_delete { |_| }
+      ).to be(record)
+    end
+
+    it "does not call the block" do
+      expect {
+        record.if_delete { |_| raise "Does not happen" }
+      }.not_to raise_error
+    end
+  end
+
+  describe "#merge" do
+    let(:extra_data) {
+      {
+        location: location,
+      }
+    }
+
+    let(:location) { double(:location) }
+
+    it "returns a new record with same identity" do
+      expect(record.merge(extra_data).identity).to eq(
+        id1: id1,
+        id2: id2,
+      )
+    end
+
+    it "returns a new record with same namespace" do
+      expect(
+        record.merge(extra_data).namespace
+      ).to eq(namespace)
+    end
+
+    it "returns a new record with merged data" do
+      merged_record = record.merge(extra_data)
+
+      expect(merged_record.to_h).to eq(
+        id1: id1,
+        id2: id2,
+        name: name,
+        location: location,
+      )
+    end
+
+    it "does not mutate the original record" do
+      expect {
+        record.merge(extra_data)
+      }.not_to change { record.to_h }
+    end
+
+    context "when attempting to overwrite the existing identity" do
+      let(:extra_data) {
+        {
+          id1: double(:new_id),
+          location: location,
+        }
+      }
+
+      it "does not change the identity" do
+        expect {
+          record.merge(extra_data)
+        }.not_to change { record.identity }
+      end
+    end
+  end
+
+  describe "#<=>" do
+    let(:deep_record) {
+      Terrestrial::AbstractRecord.new(
+        namespace,
+        primary_key_fields,
+        raw_data,
+        _depth = 5,
+      )
+    }
+
+    let(:shallow_record) {
+      Terrestrial::AbstractRecord.new(
+        namespace,
+        primary_key_fields,
+        raw_data,
+        _depth = 1,
+      )
+    }
+
+    context "when other record has deeper depth" do
+      it "is sortable by depth" do
+        expect([shallow_record, record, deep_record].sort).to eq(
+          [record, deep_record, shallow_record]
+        )
+      end
+    end
+  end
+
+  describe "#==" do
+    context "super class contract" do
+      let(:comparitor) { record.merge({}) }
+
+      it "compares" do
+        record == comparitor
+      end
+
+      context "when subclassed" do
+        subject(:record) {
+          record_subclass.new(namespace, primary_key_fields, raw_data)
+        }
+
+        let(:record_subclass) {
+          Class.new(Terrestrial::AbstractRecord) {
+            protected
+
+            def operation
+              :do_a_thing
+            end
+          }
+        }
+
+        context "when comparitor is of the wrong type" do
+          it "is not equal" do
+            expect(record.==(Object.new)).to be(false)
+          end
+        end
+
+        context "when the operation type is equal" do
+          context "when the combined `raw_data` and `identity` are equal" do
+            let(:comparitor) { record.merge({}) }
+
+            it "is equal" do
+              expect(record.==(comparitor)).to be(true)
+            end
+          end
+
+          context "when the combined `raw_data` and `identity` are not equal" do
+            let(:comparitor) { record.merge(something_else: "i'm different") }
+
+            it "is not equal" do
+              expect(record.==(comparitor)).to be(false)
+            end
+          end
+        end
+
+        context "when the operation name differs" do
+          let(:comparitor) {
+            record_class_with_different_operation.new(namespace, primary_key_fields, raw_data)
+          }
+
+          let(:record_class_with_different_operation) {
+            Class.new(Terrestrial::AbstractRecord) {
+              protected
+              def operation
+                :do_a_different_thing
+              end
+            }
+          }
+
+          it "is not equal" do
+            expect(record.==(comparitor)).to be(false)
+          end
+        end
+      end
+    end
+  end
+end