sequel_mapper 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2a26f63ff570a4dace02b8407237d137e91fcc86
-  data.tar.gz: 682421f11a6baccefbe7969510f345d17ea26d71
+  metadata.gz: dfb105e407d34250b83618b2c789687d0fe1f86f
+  data.tar.gz: 01aeb7f356ab17224b3c93f10fbf8b8204258c98
 SHA512:
-  metadata.gz: ebc65d4a2915be9f85d269c417f47d96bec45255601a8a389b88c5bdc009420fac2c9f65ad64c8cdb13fea33a877b3d8db0274264e6f3242cd2cff3f207a6111
-  data.tar.gz: 6742b37bb795d34aeadc8fd765bc76976cafcf0e5c1b24873dc5720d1631b07cca1391c3914774acb4b8026514830ea13dcd9bcb7a35d2cb762042fc712898b3
+  metadata.gz: 24b33c4a55324d01e8a37321e7a19e94ff7a4f275f0960f16fda3d63691a2fba5ee8c51f6da1a3ea4eeea2c03457e9eae7470da1e48267f3ee102711d73d882a
+  data.tar.gz: 127f9594d9409b4b09cd7c20517d7f55e2368655f06ce713de238e59af2247ede9dd0b07ae627e5876e2581e47814724693c1f1cf799735005b049a0182848bf

data/.ruby-version

@@ -1 +1 @@
-2.1.3
+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

@@ -1,15 +1,38 @@
 PATH
   remote: .
   specs:
-    sequel_mapper (0.0.1)
+    sequel_mapper (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)
@@ -28,16 +51,23 @@ GEM
     rspec-mocks (3.1.3)
       rspec-support (~> 3.1.0)
     rspec-support (3.1.2)
-    sequel (4.16.0)
+    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)
   sequel_mapper!
+
+BUNDLED WITH
+   1.10.6

data/MissingFeatures.md

@@ -0,0 +1,64 @@
+# Missing features
+
+The following features not included in SequelMapper 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.
+SequelMapper 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 SequelMapper 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 SequelMapper can use to reverse the
+operation for persistence.
+

data/README.md

@@ -1,41 +1,62 @@
 # SequelMapper
 
-**Very new, much experimental, so incomplete**
+## TL;DR
 
-## What it is
+* 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)
 
-SequelMapper is a data mapper that pulls rows out of your database and maps
-them into a graph of plain Ruby objects. The graph can then be modifed and
-persisted back into the database as a whole.
+SequelMapper (working title) is a new, currently experimental [data mapper](http://martinfowler.com/eaaCatalog/dataMapper.html) ORM implementation for Ruby.
 
-The main feature is that it fully supports all the kinds of data associations
-that you are used to with ActiveRecord but for your POROs.
+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.
 
-It is built on top of Jeremy Evans' Sequel library.
+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.
 
-## Why is it?
+## Features
 
-* It seems like ROM may not be finished any time soon and I felt I could put
-  together something functional albeit less ambitious
-* I love the Sequel library
-* I love decoupling persistence
-* Writing a complex datamapper is sure way to stall your project so I'm writing
-  one for you
-* I am a sick person who enjoys this sort of thing
+* 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
 
-So go on, persist those POROs, they don't even have to know about it.
+There are some [conspicuous missing features](https://github.com/bestie/sequel_mapper/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.
 
-## Example
+SequelMapper 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.
+
+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
-  # Let's say you have some domain objects
+
+  # 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, :comments, :categories)
-  Comment = Struct.new(:id, :post, :commenter, :body)
+  Post = Struct.new(:id, :author, :subject, :body, :created_at, :categories)
   Category = Struct.new(:id, :name, :posts)
 
-  # And a relational database with some tables that look similar
+  ## 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
+
+  ## Sequel Mapper does not manage your connection for you.
+  ## Example assumes Postgres however Sequel supports many other databases.
 
   DB = Sequel.postgres(
     host: ENV.fetch("PGHOST"),
@@ -43,70 +64,118 @@ So go on, persist those POROs, they don't even have to know about it.
     database: ENV.fetch("PGDATABASE"),
   )
 
-  user_mapper = SequelMapper::Graph.new(
-    top_level_namespace: :users,
+  # 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 = SequelMapper.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 = SequelMapper.mapper(
     datastore: DB,
-    config: mapper_config, # Config omitted
+    config: USER_MAPPER_CONFIG,
+    name: :users,
   )
 
-  # Then this may appeal to you
-
-  user = user_mapper.where(id: 1).first
-  # => [#<struct User
-  #       id=1,
-  #       first_name="Stephen",
-  #       last_name="Best",
-  #       email="bestie@gmail.com",
-  #       posts=#<SequelMapper::AssociationProxy:0x007ffbc3c7cb50 @assoc_enum=#<Enumerator::Lazy: ...>, @removed_nodes=[]>>]
-
-  user.posts
-  # => #<SequelMapper::AssociationProxy:0x007ffbc3c7cb50 @assoc_enum=#<Enumerator::Lazy: ...>, @removed_nodes=[]>
-  # That's lazily evaluated try ...
-
-  user.posts.to_a
-  # => [#<struct Post
-  #       id=1,
-  #       author=
-  #        #<struct User
-  #         id=1,
-  #         first_name="Stephen",
-  #         last_name="Best",
-  #         email="bestie@gmail.com",
-  #         posts=#<SequelMapper::AssociationProxy:0x007ffbc3c7cb50 @assoc_enum=#<Enumerator::Lazy: ...>, @removed_nodes=[]>>,
-  #       subject="Object mapping",
-  #       body="It is often tricky",
-  #       comments=#<SequelMapper::AssociationProxy:0x007ffbc59377b8 @assoc_enum=#<Enumerator::Lazy: ...>, @removed_nodes=[]>,
-  #       categories=#<SequelMapper::AssociationProxy:0x007ffbc5936138 @assoc_enum=#<Enumerator::Lazy: ...>, @removed_nodes=[]>>,
-  #      #<struct Post
-  #       id=2,
-  #       author=
-  #        #<struct User
-  #         id=1,
-  #         first_name="Stephen",
-  #         last_name="Best",
-  #         email="bestie@gmail.com",
-  #         posts=#<SequelMapper::AssociationProxy:0x007ffbc3c7cb50 @assoc_enum=#<Enumerator::Lazy: ...>, @removed_nodes=[]>>,
-  #       subject="Object mapping part 2",
-  #       body="Lazy load all the things!",
-  #       comments=#<SequelMapper::AssociationProxy:0x007ffbc5935990 @assoc_enum=#<Enumerator::Lazy: ...>, @removed_nodes=[]>,
-  #       categories=#<SequelMapper::AssociationProxy:0x007ffbc592fe50 @assoc_enum=#<Enumerator::Lazy: ...>, @removed_nodes=[]>>]
-
-  # And then access the comments and so on ...
+  ## 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=#<SequelMapper::CollectionMutabilityProxy:7ff57192d510 >,
+
+```
+
+## Running the tests
+
+### Set the following environment variables
+* PGHOST
+* PGUSER
+* PGDATABASE
+
+### Create a test database
+
+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
+```
+
+### Should anything go awry
+
+Drop the test database and start fresh
+
+```
+$ bundle exec rake db:drop
 ```
 
 ## Installation
 
-Add this line to your application's Gemfile:
+This library is still pre 1.0 so please lock down your version and update with
+care.
 
-```ruby
-gem 'sequel_mapper'
+Add the following to your `Gemfile`.
+
+```
+gem "sequel_mapper", "0.0.3"
 ```
 
 And then execute:
 
     $ bundle
 
-Or install it yourself as:
+Or install it manually:
 
     $ gem install sequel_mapper
 

data/Rakefile

@@ -1,2 +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 SequelMapper::SequelTestSupport
+
+  task :setup => [:create] do
+    create_tables(BLOG_SCHEMA)
+  end
+
+  task :create do
+    create_database
+  end
+
+  task :drop do
+    drop_database
+  end
+end