terrestrial 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5d357727f08469741639890993a24a4b7e319269
-  data.tar.gz: 4c623940088221dbab9f78f25d0cf747b6d62c68
+  metadata.gz: 0ba5176dafbe142a9b5f25e00902eec58bd5b858
+  data.tar.gz: 8674e2b27c6548db3d39b05cd095c6c4d5b9a132
 SHA512:
-  metadata.gz: f1f8c89883b65df9b38bd3f2a38b5f7f8ea4e31c19cfb94c932805229aab9f1486ea21036f1cc3192cdc4e023eed20514fd7c7c8774616c884f077a2be7ecec1
-  data.tar.gz: a105ec0392cdc89a45253f8851a965f1e85e2b86eabbb3fdfc2b9c6d913dbddc12e49417f747f9a041062badb752794c13060294408cae0f313591db7a55d2c0
+  metadata.gz: fb86ee61ccd132a3b1bcaa99b0ab225e59b387cd80c1425d09e847c5f5d52b48610287ae95039d249f8d366fc13abc2045d9ba213eeb963a694f11fb3a068ec0
+  data.tar.gz: 96c6cfc35fdeba513882de149e1dc751bd6c20628a2743555d1be451b637745dc5ba690c3bcf9db0ac4a7b2a5d52a830d6d9ab8efa8086f89451d2b2ad2ed333

data/.gitignore

@@ -1,9 +1 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
+.env

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+2.2.3

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,28 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all
+people who contribute through reporting issues, posting feature requests,
+updating documentation, submitting pull requests or patches, and other
+activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual
+language or imagery, derogatory comments or personal attacks, trolling, public
+or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct. Project maintainers who do not
+follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening an issue or contacting one or more of the project
+maintainers.
+
+This Code of Conduct is adapted from the [Contributor
+Covenant](http:contributor-covenant.org), version 1.0.0, available at
+[http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile.lock

@@ -0,0 +1,73 @@
+PATH
+  remote: .
+  specs:
+    terrestrial (0.0.3)
+      activesupport (~> 4.0)
+      fetchable (~> 1.0)
+      sequel (~> 4.16)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.2.4)
+      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)
+      builder (>= 2.1.2)
+      diff-lcs (>= 1.1.3)
+      gherkin (~> 2.12)
+      multi_json (>= 1.7.5, < 2.0)
+      multi_test (>= 0.1.2)
+    diff-lcs (1.2.5)
+    fetchable (1.0.0)
+    gherkin (2.12.2)
+      multi_json (~> 1.3)
+    i18n (0.7.0)
+    json (1.8.3)
+    method_source (0.8.2)
+    minitest (5.8.3)
+    multi_json (1.11.1)
+    multi_test (0.1.2)
+    pg (0.17.1)
+    pry (0.10.1)
+      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)
+      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)
+    slop (3.6.0)
+    thread_safe (0.3.5)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.7)
+  cucumber
+  pg (~> 0.17.1)
+  pry (~> 0.10.1)
+  rake (~> 10.0)
+  rspec (~> 3.1)
+  terrestrial!
+
+BUNDLED WITH
+   1.10.6

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Stephen Best
+
+MIT License
+
+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/MissingFeatures.md

@@ -0,0 +1,64 @@
+# Missing features
+
+The following features not included in Terrestrial are omitted purposefully to
+keep the library simple and encourage good practices in application code.
+
+Please open an issue if you feel like any of these features are essential or if
+you think you can contribute to a solution please open an issue to discuss.
+
+## Coercion
+
+Database supported types will be returned as expected, `Fixnum`, `DateTime`, `nil` etc.
+Should you wish to enhance this data, every row is passed into the mapping's
+factory function where you have the opportunity to do arbitrary transformations
+before instantiating the domain object.
+
+\*see note on transforming row data
+
+## Validation
+
+This is the concern of your domain model and/or application boundaries.
+Terrestrial allows you to persist any object you wish assuming schema
+compatibility.
+
+## Database column name aliasing
+
+While at first glance this is a simple feature, the abstraction starts to leak
+when the using the query interface and guaranteeing all queries are substituted
+perfectly is beyond the scope of the current version.
+
+Should you wish to simply pass a column's key with a different parameter name
+then you can again lean on the factory function to transform the row's data
+before the domain object receives it.
+
+\*see note on transforming row data
+
+## Cascade deletion
+
+This is chiefly a data concern and is handled by a good database more
+efficiently and effectively than any ORM could hope.
+
+## Database generated IDs and timestamps
+
+While database generated values may work, available only after an object is
+retrieved, they are not currently supported.
+
+Data important to your domain should be generated in your application layer.
+UUIDs make much more flexible identifiers for domain objects and further enable
+decoupling and fast tests.
+
+Timestamps are useful and important to most applications however if they are
+used in your domain they should be pushed from explicitly from application
+layer. You should again find this affords you more flexibility and decoupling.
+
+There is absolutely nothing wrong with data added at time of persistence for
+auditing purposes but Terrestrial will make you actively decide whether this
+data should be available to the domain and what should be explicitly added.
+
+\* Transforming row data
+
+Adding a custom factory method to transform row data before passing it to the
+domain layer is highly encouraged. However, ensure that for each custom factory
+a serializer function is also supplied that Terrestrial can use to reverse the
+operation for persistence.
+

data/README.md

@@ -1,36 +1,181 @@
 # Terrestrial
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/terrestrial`. To experiment with that code, run `bin/console` for an interactive prompt.
+## TL;DR
 
-TODO: Delete this and the text above, and describe your gem
+* 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)
 
-## Installation
+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.
+
+## Features
+
+* Associations (belongs_to, has_many, has_many_through)
+* Automatic 'convention over configuration' that is fully customizable
+* Lazy loading for database read efficiency
+* 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
+of the problems listed please open an issue to discuss.
+
+Terrestrial does not reinvent the wheel with querying abstraction and
+migrations, instead these responsibilities are delegated to Sequel such that
+its full power can be utilised.
 
-Add this line to your application's Gemfile:
+For [querying](http://sequel.jeremyevans.net/rdoc/files/doc/querying_rdoc.html),
+[migrations](http://sequel.jeremyevans.net/rdoc/files/doc/migration_rdoc.html)
+and creating your [database connection](http://sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html)
+see the Sequel documentation.
+
+## Getting started
+
+Please try this out, experiment, open issues and pull requests. Please read the
+code of conduct first.
 
 ```ruby
-gem 'terrestrial'
+
+  # 1. Define some domain objects, structs will surfice for the example
+
+  User = Struct.new(:id, :first_name, :last_name, :email, :posts)
+  Post = Struct.new(:id, :author, :subject, :body, :created_at, :categories)
+  Category = Struct.new(:id, :name, :posts)
+
+  ## Also assume that a conventional database schema (think Rails) is in place,
+  ## a column for each of the struct's attributes will be present. The posts
+  ## table will have `author_id` as a foreign key to the users table. There is
+  ## a join table named `categories_to_posts` which facilitates the many to
+  ## many relationship.
+
+  # 2. Configure a Sequel database connection
+
+  ## Terrestrial does not manage your connection for you.
+  ## Example assumes Postgres however Sequel supports many other databases.
+
+  DB = Sequel.postgres(
+    host: ENV.fetch("PGHOST"),
+    user: ENV.fetch("PGUSER"),
+    database: ENV.fetch("PGDATABASE"),
+  )
+
+  # 3. Configure mappings and associations
+
+  ## 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)
+    .setup_mapping(:users) { |users|
+      users.has_many(:posts, foreign_key: :author_id)
+    }
+    .setup_mapping(:posts) { |posts|
+      posts.belongs_to(:author, mapping_name: :users)
+      posts.has_many_through(:categories)
+    }
+    .setup_mapping(:categories) { |categories|
+      categories.has_many_through(:posts)
+    }
+
+  # 4. Create a mapper by combining a connection and a configuration
+
+  USER_MAPPER = Terrestrial.mapper(
+    datastore: DB,
+    config: USER_MAPPER_CONFIG,
+    name: :users,
+  )
+
+  ## 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.
+
+  # 5. Create some objects
+
+  user = User.new(
+    "2f0f791c-47cf-4a00-8676-e582075bcd65",
+    "Hansel",
+    "Trickett",
+    "hansel@tricketts.org",
+    [],
+  )
+
+  user.posts << Post.new(
+    "9b75fe2b-d694-4b90-9137-6201d426dda2",
+    user,
+    "Things that I like",
+    "I like fish and scratching",
+    Time.parse("2015-10-03 21:00:00 UTC"),
+    [],
+  )
+
+  # 6. Save them
+
+  USER_MAPPER.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
+
+  # => #<struct User
+  #  id="2f0f791c-47cf-4a00-8676-e582075bcd65",
+  #  first_name="Stephen",
+  #  last_name="Best",
+  #  email="bestie@gmail.com",
+  #  posts=#<Terrestrial::CollectionMutabilityProxy:7ff57192d510 >,
+
 ```
 
-And then execute:
+## Running the tests
 
-    $ bundle
+### Set the following environment variables
+* PGHOST
+* PGUSER
+* PGDATABASE
 
-Or install it yourself as:
+### Create a test database
 
-    $ gem install terrestrial
+This will create a database named from the value of `PGDATABASE`
+
+```
+$ bundle exec rake db:create
+```
+
+### Run all tests (RSpec and Cucumber)
+```
+$ bundle exec rake
+```
 
-## Usage
+### Should anything go awry
 
-TODO: Write usage instructions here
+Drop the test database and start fresh
 
-## Development
+```
+$ bundle exec rake db:drop
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake false` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+## Installation
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+This library is still pre 1.0 so please lock down your version and update with
+care.
 
-## Contributing
+Add the following to your `Gemfile`.
+
+```
+gem "terrestrial", "0.0.3"
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/terrestrial.
+And then execute:
+
+    $ bundle
+
+Or install it manually:
+
+    $ gem install terrestrial
 

data/Rakefile

@@ -1 +1,31 @@
 require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+require 'cucumber/rake/task'
+
+RSpec::Core::RakeTask.new
+Cucumber::Rake::Task.new
+
+task :default => [
+  :spec,
+  :cucumber,
+]
+
+require_relative "spec/support/sequel_test_support"
+require_relative "spec/support/blog_schema"
+
+namespace :db do
+  include Terrestrial::SequelTestSupport
+
+  task :setup => [:create] do
+    create_tables(BLOG_SCHEMA)
+  end
+
+  task :create do
+    create_database
+  end
+
+  task :drop do
+    drop_database
+  end
+end

data/TODO.md

@@ -0,0 +1,41 @@
+# TODOs
+
+In no particular order
+
+## General
+* 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
+
+## 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
+* 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
+
+# Hopefully done
+
+## Persistence
+* Efficient saving
+  - Part one, if it wasn't loaded it wasn't modified, check identity map
+  - Part two, dirty tracking
+
+## Associations
+* Eager loading
+
+## Configuration
+* Automatic config generation based on schema, foreign keys etc
+* Config to take either a classes or callable factory

data/features/env.rb

@@ -0,0 +1,60 @@
+require "pry"
+require "sequel"
+require "terrestrial"
+require_relative "../spec/support/sequel_test_support"
+
+module ExampleRunnerSupport
+  def example_eval_concat(code_strings)
+    example_eval(code_strings.join("\n"))
+  end
+
+  def example_eval(code_string)
+    example_module.module_eval(code_string)
+  rescue Object => e
+    binding.pry if ENV["DEBUG"]
+    raise e
+  end
+
+  def example_exec(&block)
+    example_exec.module_eval(&block)
+  end
+
+  def example_module
+    @example_module ||= Module.new
+  end
+
+  def normalise_inspection_string(string)
+    string
+      .strip
+      .gsub(/[\n\s]+/, " ")
+      .gsub(/\:[0-9a-f]{12}/, ":<<object id removed>>")
+  end
+
+  def parse_schema_table(string)
+    string.each_line.drop(2).map { |line|
+      name, type = line.split("|").map(&:strip)
+      {
+        name: name,
+        type: Object.const_get(type),
+      }
+    }
+  end
+end
+
+module DatabaseSupport
+  def create_table(name, schema)
+    Terrestrial::SequelTestSupport.create_tables(
+      tables: {
+        name => schema,
+      },
+      foreign_keys: [],
+    )
+  end
+end
+
+Before do
+  Terrestrial::SequelTestSupport.drop_tables
+end
+
+World(ExampleRunnerSupport)
+World(DatabaseSupport)

data/features/example.feature

@@ -0,0 +1,120 @@
+Feature: Basic setup
+
+  Scenario: Setup with conventional configuration
+    Given the domain objects are defined
+      """
+        User = Struct.new(:id, :first_name, :last_name, :email, :posts)
+        Post = Struct.new(:id, :author, :subject, :body, :created_at, :categories)
+        Category = Struct.new(:id, :name, :posts)
+      """
+    And a conventionally similar database schema for table "users"
+      """
+        Column      | Type
+       ------------ +---------
+        id          | String
+        first_name  | String
+        last_name   | String
+        email       | String
+      """
+    And a conventionally similar database schema for table "posts"
+      """
+        Column      | Type
+       -------------+---------
+        id          | String
+        author_id   | String
+        subject     | String
+        body        | String
+        created_at  | DateTime
+      """
+    And a conventionally similar database schema for table "categories"
+      """
+        Column      | Type
+       -------------+---------
+        id          | String
+        name        | String
+      """
+    And a conventionally similar database schema for table "categories_to_posts"
+      """
+        Column      | Type
+       -------------+---------
+        post_id     | String
+        category_id | String
+      """
+    And a database connection is established
+      """
+        DB = Sequel.postgres(
+          host: ENV.fetch("PGHOST"),
+          user: ENV.fetch("PGUSER"),
+          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(
+          datastore: DB,
+          mappings: MAPPINGS_CONFIG,
+        )
+      """
+    When a new graph of objects are created
+      """
+        user = User.new(
+          "2f0f791c-47cf-4a00-8676-e582075bcd65",
+          "Hansel",
+          "Trickett",
+          "hansel@tricketts.org",
+          [],
+        )
+
+        user.posts << Post.new(
+          "9b75fe2b-d694-4b90-9137-6201d426dda2",
+          user,
+          "Things that I like",
+          "I like fish and scratching",
+          Time.parse("2015-10-03 21:00:00 UTC"),
+          [],
+        )
+      """
+    And the new graph is saved
+      """
+        MAPPERS[:users].save(user)
+      """
+    And the following query is executed
+      """
+        user = MAPPERS[:users].where(id: "2f0f791c-47cf-4a00-8676-e582075bcd65").first
+      """
+    Then the persisted user object is returned with lazy associations
+      """
+        #<struct User id="2f0f791c-47cf-4a00-8676-e582075bcd65",
+          first_name="Hansel",
+          last_name="Trickett",
+          email="hansel@tricketts.org",
+          posts=#<Terrestrial::CollectionMutabilityProxy:7fa4817aa148
+        >>
+      """
+    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>,
+          subject="Things that I like",
+          body="I like fish and scratching",
+          created_at=2015-10-03 21:00:00 UTC,
+          categories=#<Terrestrial::CollectionMutabilityProxy:7fec5ac296f8
+        >>]
+      """