terrestrial 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0ba5176dafbe142a9b5f25e00902eec58bd5b858
-  data.tar.gz: 8674e2b27c6548db3d39b05cd095c6c4d5b9a132
+  metadata.gz: c61b139216aa29d6468f16cabdbb135d7c68cbc1
+  data.tar.gz: ab6960d54b3c7546f8d95a6e337efddaef166a7f
 SHA512:
-  metadata.gz: fb86ee61ccd132a3b1bcaa99b0ab225e59b387cd80c1425d09e847c5f5d52b48610287ae95039d249f8d366fc13abc2045d9ba213eeb963a694f11fb3a068ec0
-  data.tar.gz: 96c6cfc35fdeba513882de149e1dc751bd6c20628a2743555d1be451b637745dc5ba690c3bcf9db0ac4a7b2a5d52a830d6d9ab8efa8086f89451d2b2ad2ed333
+  metadata.gz: b9a11c083365c86dce49908720970407824645d40802fb5adbfd9d9b7adb8fd22f4a2b539e35edd4d630be0881413f3b0ee5063b3a20011707b33edc0687d72d
+  data.tar.gz: 7e3a194ff7a687b28fdf62ba993af5b83d5e4294c439d14cce8489f8f2439eadc8684842cfc557a642574076b831e6a5e6eb94347e5ee53079b41793c3349348

data/.ruby-version

@@ -1 +1 @@
-2.2.3
+2.3.1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    terrestrial (0.0.3)
+    terrestrial (0.3.0)
       activesupport (~> 4.0)
       fetchable (~> 1.0)
       sequel (~> 4.16)
@@ -9,49 +9,54 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (4.2.4)
+    activesupport (4.2.7.1)
       i18n (~> 0.7)
       json (~> 1.7, >= 1.7.7)
       minitest (~> 5.1)
       thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
     builder (3.2.2)
-    coderay (1.1.0)
-    cucumber (1.3.20)
+    coderay (1.1.1)
+    cucumber (2.4.0)
       builder (>= 2.1.2)
+      cucumber-core (~> 1.5.0)
+      cucumber-wire (~> 0.0.1)
       diff-lcs (>= 1.1.3)
-      gherkin (~> 2.12)
+      gherkin (~> 4.0)
       multi_json (>= 1.7.5, < 2.0)
       multi_test (>= 0.1.2)
+    cucumber-core (1.5.0)
+      gherkin (~> 4.0)
+    cucumber-wire (0.0.1)
     diff-lcs (1.2.5)
     fetchable (1.0.0)
-    gherkin (2.12.2)
-      multi_json (~> 1.3)
+    gherkin (4.0.0)
     i18n (0.7.0)
     json (1.8.3)
     method_source (0.8.2)
-    minitest (5.8.3)
-    multi_json (1.11.1)
+    minitest (5.9.1)
+    multi_json (1.12.1)
     multi_test (0.1.2)
     pg (0.17.1)
-    pry (0.10.1)
+    pry (0.10.4)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
       slop (~> 3.4)
-    rake (10.1.0)
-    rspec (3.1.0)
-      rspec-core (~> 3.1.0)
-      rspec-expectations (~> 3.1.0)
-      rspec-mocks (~> 3.1.0)
-    rspec-core (3.1.7)
-      rspec-support (~> 3.1.0)
-    rspec-expectations (3.1.2)
+    rake (10.5.0)
+    rspec (3.5.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+    rspec-core (3.5.3)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.1.0)
-    rspec-mocks (3.1.3)
-      rspec-support (~> 3.1.0)
-    rspec-support (3.1.2)
-    sequel (4.26.0)
+      rspec-support (~> 3.5.0)
+    rspec-mocks (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+    sequel (4.39.0)
     slop (3.6.0)
     thread_safe (0.3.5)
     tzinfo (1.2.2)
@@ -70,4 +75,4 @@ DEPENDENCIES
   terrestrial!
 
 BUNDLED WITH
-   1.10.6
+   1.12.5

data/README.md

@@ -4,22 +4,27 @@
 
 * A Ruby ORM that enables DDD and clean architectural styles.
 * Persists plain objects while supporting arbitrarily deeply nested / circular associations
-* Provides excellent database and query building support courtesy of [Sequel library](https://github.com/jeremyevans/sequel)
+* Provides excellent database and query building support courtesy of the [Sequel library](https://github.com/jeremyevans/sequel)
 
 Terrestrial is a new, currently experimental [data mapper](http://martinfowler.com/eaaCatalog/dataMapper.html) ORM implementation for Ruby.
 
 The aim is to provide a convenient way to query and persist graphs of Ruby objects (think models with associations), while keeping those object completely isolated and decoupled from the database.
 
 In contrast to Ruby's many [active record](http://martinfowler.com/eaaCatalog/activeRecord.html) implementations, domain objects require no special inherited or mixed in behavior in order to be persisted.
+In fact Terrestrial has no specific requirements for domain objects at all.
+While there is a simple default, `.new` and `#to_h`, you may define arbitrary
+functions (per mapping) and expose no reader methods at all.
 
 ## Features
 
+* Absolute minimum coupling between domain and persistence
+* Persistence of plain or arbitrary objects
 * Associations (belongs_to, has_many, has_many_through)
 * Automatic 'convention over configuration' that is fully customizable
-* Lazy loading for database read efficiency
+* Lazy loading of associations
+* Optional eager loading to avoid the `n + 1` query problem
 * Dirty tracking for database write efficiency
 * Predefined queries, scopes or subsets
-* Eager loading to avoid the `n + 1` query problem
 
 There are some [conspicuous missing features](https://github.com/bestie/terrestrial/blob/master/MissingFeatures.md)
 that you may want to read more about. If you want to contribute to solving any
@@ -69,30 +74,34 @@ code of conduct first.
   ## This is kept separate from your domain models as knowledge of the schema
   ## is required to wire them up.
 
-  USER_MAPPER_CONFIG = Terrestrial.config(DB)
+  MAPPINGS = Terrestrial.config(DB)
     .setup_mapping(:users) { |users|
+      users.class(User) # Specify a class and the constructor will be used
       users.has_many(:posts, foreign_key: :author_id)
     }
     .setup_mapping(:posts) { |posts|
+      # To avoid directly specifiying a class, a factory function can be used instead
+      posts.factory(->(attrs) { Post.new(attrs) })
       posts.belongs_to(:author, mapping_name: :users)
       posts.has_many_through(:categories)
     }
     .setup_mapping(:categories) { |categories|
+      categories.class(Category)
       categories.has_many_through(:posts)
     }
 
-  # 4. Create a mapper by combining a connection and a configuration
+  # 4. Create an object store by combining a connection and a configuration
 
-  USER_MAPPER = Terrestrial.mapper(
+  OBJECT_STORE = Terrestrial.object_store(
     datastore: DB,
-    config: USER_MAPPER_CONFIG,
-    name: :users,
+    mappings: MAPPINGS,
   )
 
-  ## You are not limted to one mapper configuration or one database connection.
-  ## To handle complex situations you may create several segregated mappings
-  ## for your separate aggregate roots, potentially utilising multiple
-  ## databases and different domain object classes/compositions.
+  ## You are not limted to one object store configuration or one database
+  ## connection. To handle complex situations you may create several segregated
+  ## mappings and object stores for your separate aggregate roots, potentially
+  ## utilising multiple databases and different domain object
+  ## classes/compositions.
 
   # 5. Create some objects
 
@@ -115,13 +124,13 @@ code of conduct first.
 
   # 6. Save them
 
-  USER_MAPPER.save(user)
+  OBJECT_STORE[:users].save(user)
 
   ## Only the (aggregate) root object needs to be passed to the mapper.
 
   # 7. Query
 
-  user = USER_MAPPER.where(id: "2f0f791c-47cf-4a00-8676-e582075bcd65").first
+  user = OBJECT_STORE[:users].where(id: "2f0f791c-47cf-4a00-8676-e582075bcd65").first
 
   # => #<struct User
   #  id="2f0f791c-47cf-4a00-8676-e582075bcd65",
@@ -134,7 +143,10 @@ code of conduct first.
 
 ## Running the tests
 
-### Set the following environment variables
+### ENV vars
+
+The test suite expects the following standard Postgres environment variables.
+
 * PGHOST
 * PGUSER
 * PGDATABASE
@@ -147,9 +159,15 @@ This will create a database named from the value of `PGDATABASE`
 $ bundle exec rake db:create
 ```
 
-### Run all tests (RSpec and Cucumber)
+### Run all tests RSpec and Cucumber
+
+The RSpec tests run twice, once against Sequel/Postgres and again against
+an in-memory datastore.
+
+Cucumber runs only against the Sequel/Postgres backend.
+
 ```
-$ bundle exec rake
+$ bin/test
 ```
 
 ### Should anything go awry

data/Rakefile

@@ -1,15 +1,10 @@
 require "bundler/gem_tasks"
 
-require 'rspec/core/rake_task'
-require 'cucumber/rake/task'
-
-RSpec::Core::RakeTask.new
-Cucumber::Rake::Task.new
+task :test_suite do
+  puts "Run bin/test to run the entire test suite"
+end
 
-task :default => [
-  :spec,
-  :cucumber,
-]
+task :default => [:test_suite]
 
 require_relative "spec/support/sequel_test_support"
 require_relative "spec/support/blog_schema"

data/TODO.md

@@ -2,29 +2,20 @@
 
 In no particular order
 
-## General
+* User defined default settings for all mappings
 * Refactor, methods too big, objects missing
 * Name things better
-* Better support swapping out DB for in memory datasets
-* `#eager_load!` that raises an error when traversing outside the eagerly
-  loaded data
+* Full adaptorization of the database, refactor some Sequel specific things
+  into the adapter
 
-## Querying
-* Querying API, what would a repository with some arbitrary queries look like?
-  - e.g. an association on post called `burger_comments` that finds comments
-    with the word burger in them
-* Add other querying methods from association proxies or remove entirely
-  - Depends on nailing down the querying API
+## Candidate features to consider
+* Column aliasing
+* Callbacks e.g. after_save, after_insert as functions defined in mapping
+* Database generated IDs and Timestamps (perhaps implemented as callbacks)
 * When possible optimise blocks given to `AssociationProxy#select` with
   Sequel's `#where` with block [querying API](http://sequel.jeremyevans.net/rdoc/files/doc/cheat_sheet_rdoc.html#label-AND%2FOR%2FNOT)
-
-## Associations
-* Read only associations
-  - Loaded objects would be immutable
-  - Collection proxy would have no #push or #remove
-  - Skipped when dumping
-* Associations defined with a join
-* Composable associations
+* `#eager_load!` that raises an error when traversing outside the eagerly
+  loaded data
 
 # Hopefully done
 
@@ -32,10 +23,26 @@ In no particular order
 * Efficient saving
   - Part one, if it wasn't loaded it wasn't modified, check identity map
   - Part two, dirty tracking
+* Support swapping out DB for in memory datasets
 
 ## Associations
 * Eager loading
 
+## Querying
+* Querying API, what would a repository with some arbitrary queries look like?
+  - e.g. an association on post called `burger_comments` that finds comments
+    with the word burger in them
+
 ## Configuration
 * Automatic config generation based on schema, foreign keys etc
 * Config to take either a classes or callable factory
+
+# Not happening (at least for now)
+
+## Associations
+* Read only associations
+  - Loaded objects would be immutable
+  - Collection proxy would have no #push or #remove
+  - Skipped when dumping
+* Associations defined with a join
+* Composable associations

data/bin/test

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+
+require "bundler"
+Bundler.setup
+
+ADAPTERS = ["memory", "sequel"]
+
+module TerrestrialTesting
+  module_function def run_rspec_with_adapter(adapter)
+    puts "Running RSpec suite for `#{adapter}` adapter"
+    puts "Run following command to replicate"
+    puts "ADAPTER=#{adapter} bundle exec rspec"
+    puts ""
+
+    system("ADAPTER=#{adapter} rspec")
+  end
+
+  module_function def run_cucumber
+    system("cucumber")
+  end
+end
+
+exit_successes = ADAPTERS.map do |adapter|
+  TerrestrialTesting.run_rspec_with_adapter(adapter)
+end
+
+if exit_successes.all?
+  exit_successes.push(TerrestrialTesting.run_cucumber)
+end
+
+exit exit_successes.all? ? 0 : 1

data/docs/domain_object_contract.md

@@ -0,0 +1,50 @@
+# Domain object contract
+
+## Configurable defaults
+
+For saving a new or updating an existing object, Terrestrial assumes that your
+domain objects implement a `#to_h` method that returns a Hash (keyed with
+Symbols) of attributes that can be directly inserted into the database.
+
+The `#to_h` interface is common in Ruby, `Struct` and `OpenStruct` both
+implement this behavior as standard.
+
+*This is the only method terrestrial will ever call on your objects*
+
+For loading previously persisted objects, Terrestrial assumes that your domain
+objects can be instantiated by calling `.new` on the specified or inferred
+class with a Hash (keyed with Symbols) of attributes that match the database
+column names.
+
+This attributes Hash into constructor interface is supported by `OpenStruct`
+but not by `Struct`. Terrestrial will treats `Struct` as a special case and
+translates attributes into an ordered array of values. See `Terrestrial::StructAdapter`
+
+## Custom serializers and factories
+
+If you prefer Terrestrial not to call any methods on your domain objects this
+is absolutely possible and encouraged.
+
+A serializer function should be a lambda like object capable of converting a
+domain object into a Hash (keyed by Symbols) and its persistable values.
+
+For the default scenario detailed above Terrestrial generates the following
+lambda.
+
+```ruby
+  ->(domain_object) { domain_object.to_h }
+```
+
+A factory lambda will be called with same Hash of Symbol to value as above.
+
+The default configuration would generate something like this for a users mapping.
+
+```ruby
+  ->(attributes_hash) { User.new(attributes_hash) }
+```
+
+Providing bespoke functions can achieve many goals including:
+  * Looser coupling to Terrestrial
+  * Translation, modification or decoration of incoming and outgoing data
+  * Dynamically select a class (like Rails STI that doesn't necessarily need
+    inheritance)

data/features/env.rb

@@ -27,7 +27,8 @@ module ExampleRunnerSupport
     string
       .strip
       .gsub(/[\n\s]+/, " ")
-      .gsub(/\:[0-9a-f]{12}/, ":<<object id removed>>")
+      .gsub(/ \>/, ">")
+      .gsub(/\:0x[0-9a-f]{14}/, ":<<object id removed>>")
   end
 
   def parse_schema_table(string)
@@ -42,12 +43,9 @@ module ExampleRunnerSupport
 end
 
 module DatabaseSupport
-  def create_table(name, schema)
+  def create_table(name, columns)
     Terrestrial::SequelTestSupport.create_tables(
-      tables: {
-        name => schema,
-      },
-      foreign_keys: [],
+      name => columns,
     )
   end
 end

data/features/example.feature

@@ -48,28 +48,28 @@ Feature: Basic setup
           database: ENV.fetch("PGDATABASE"),
         )
       """
-    And the associations are defined in the mapper configuration
-      """
-      MAPPINGS_CONFIG = Terrestrial.config(DB)
-        .setup_mapping(:users) { |users|
-          users.class(User)
-          users.has_many(:posts, foreign_key: :author_id)
-        }
-        .setup_mapping(:posts) { |posts|
-          posts.class(Post)
-          posts.belongs_to(:author, mapping_name: :users)
-          posts.has_many_through(:categories)
-        }
-        .setup_mapping(:categories) { |categories|
-          categories.class(Category)
-          categories.has_many_through(:posts)
-        }
-      """
-    And a mapper is instantiated
-      """
-        MAPPERS = Terrestrial.mappers(
+    And the associations are defined in the configuration
+      """
+        MAPPINGS = Terrestrial.config(DB)
+          .setup_mapping(:users) { |users|
+            users.class(User)
+            users.has_many(:posts, foreign_key: :author_id)
+          }
+          .setup_mapping(:posts) { |posts|
+            posts.class(Post)
+            posts.belongs_to(:author, mapping_name: :users)
+            posts.has_many_through(:categories)
+          }
+          .setup_mapping(:categories) { |categories|
+            categories.class(Category)
+            categories.has_many_through(:posts)
+          }
+      """
+    And a object store is instantiated
+      """
+        OBJECT_STORE = Terrestrial.object_store(
           datastore: DB,
-          mappings: MAPPINGS_CONFIG,
+          mappings: MAPPINGS,
         )
       """
     When a new graph of objects are created
@@ -93,11 +93,11 @@ Feature: Basic setup
       """
     And the new graph is saved
       """
-        MAPPERS[:users].save(user)
+        OBJECT_STORE[:users].save(user)
       """
     And the following query is executed
       """
-        user = MAPPERS[:users].where(id: "2f0f791c-47cf-4a00-8676-e582075bcd65").first
+        user = OBJECT_STORE[:users].where(id: "2f0f791c-47cf-4a00-8676-e582075bcd65").first
       """
     Then the persisted user object is returned with lazy associations
       """
@@ -105,16 +105,16 @@ Feature: Basic setup
           first_name="Hansel",
           last_name="Trickett",
           email="hansel@tricketts.org",
-          posts=#<Terrestrial::CollectionMutabilityProxy:7fa4817aa148
-        >>
+          posts=#<Terrestrial::CollectionMutabilityProxy:0x007f9d8aa93bf0>
+        >
       """
     And the user's posts will be loaded once the association proxy receives an Enumerable message
       """
         [#<struct Post id="9b75fe2b-d694-4b90-9137-6201d426dda2",
-          author=#<Terrestrial::LazyObjectProxy:7fec5ac2a5f8 key_fields={:id=>"2f0f791c-47cf-4a00-8676-e582075bcd65"} lazy_object=nil>,
+          author=#<Terrestrial::LazyObjectProxy:0x007f81b2b86d30 key_fields={:id=>"2f0f791c-47cf-4a00-8676-e582075bcd65"} lazy_object=nil>,
           subject="Things that I like",
           body="I like fish and scratching",
           created_at=2015-10-03 21:00:00 UTC,
-          categories=#<Terrestrial::CollectionMutabilityProxy:7fec5ac296f8
-        >>]
+          categories=#<Terrestrial::CollectionMutabilityProxy:0x007f9d8ad88d38>
+        >]
       """