rom-repository 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4ae5380662bd3fb3fb249bf893a491bb0accbb35
+  data.tar.gz: 43da8d866c970abe7d471a19ccee12d9882d6d87
+SHA512:
+  metadata.gz: c9fb3246025ba68d17f37e4364263975dba15776c9e516ea9caabb982a22b54555c9ab1ca8fb1eeaebae767b75c514b5aa2e06b3a550675e3cd4f7d23724b0f2
+  data.tar.gz: 0cde9b16532c6ab85b063480af8bacba6e05f668710752a3f94b07f4685ea0250a203dde2019565019dd3df6a258872085ebfb0fd16dc0ae49fc29356a501c75

data/.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--order random
+--require ./spec/spec_helper

data/.travis.yml

@@ -0,0 +1,31 @@
+language: ruby
+sudo: false
+cache: bundler
+bundler_args: --without yard guard benchmarks tools
+before_script:
+  - psql -c 'create database rom;' -U postgres
+script: "bundle exec rake ci"
+rvm:
+  - 2.0
+  - 2.1
+  - 2.2
+  - rbx-2
+  - jruby
+  - jruby-head
+  - ruby-head
+env:
+  global:
+    - CODECLIMATE_REPO_TOKEN=173b95dae5c6ac281bc36a4b212291a89fed9b520b39a86bafdf603692250e60
+    - JRUBY_OPTS='--dev -J-Xmx1024M'
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head
+    - rvm: rbx-2
+notifications:
+  webhooks:
+    urls:
+      - https://webhooks.gitter.im/e/39e1225f489f38b0bd09
+    on_success: change
+    on_failure: always
+    on_start: false

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# v0.0.1 2015-08-05
+
+First public release \o/
+
+### Added
+
+* `Relation#combine_parents` for auto-combine using eager-loading strategy aka
+  relation composition (solnic)
+* `Relation#combine_children` for auto-combine using eager-loading strategy aka
+  relation composition (solnic)
+* `Relation#wrap_parent` for auto-wrap using inner join (solnic)
+* `Relation.view` for explicit relation view definitions with header and query (solnic)
+* Auto-mapping feature which builds mappers that turn relations into simple structs (solnic)

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rom', github: 'rom-rb/rom', branch: 'master'
+gem 'rom-sql', github: 'rom-rb/rom-sql', branch: 'master'
+gem 'inflecto'
+
+group :test do
+  gem 'rspec'
+  gem 'byebug', platforms: :mri
+  gem 'pg', platforms: [:mri, :rbx]
+  gem 'pg_jruby', platforms: :jruby
+  gem "codeclimate-test-reporter", require: nil
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Piotr Solnica
+
+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/README.md

@@ -0,0 +1,136 @@
+[gem]: https://rubygems.org/gems/rom-repository
+[travis]: https://travis-ci.org/rom-rb/rom-repository
+[gemnasium]: https://gemnasium.com/rom-rb/rom-repository
+[codeclimate]: https://codeclimate.com/github/rom-rb/rom-repository
+[inchpages]: http://inch-ci.org/github/rom-rb/rom-repository
+
+# ROM::Repository
+
+[![Gem Version](https://badge.fury.io/rb/rom-repository.svg)][gem]
+[![Build Status](https://travis-ci.org/rom-rb/rom-repository.svg?branch=master)][travis]
+[![Dependency Status](https://gemnasium.com/rom-rb/rom-repository.png)][gemnasium]
+[![Code Climate](https://codeclimate.com/github/rom-rb/rom-repository/badges/gpa.svg)][codeclimate]
+[![Test Coverage](https://codeclimate.com/github/rom-rb/rom-repository/badges/coverage.svg)][codeclimate]
+[![Inline docs](http://inch-ci.org/github/rom-rb/rom-repository.svg?branch=master)][inchpages]
+
+Repository for [ROM](https://github.com/rom-rb/rom) with auto-mapping and relation
+extensions.
+
+## Conventions & Definitions
+
+Repositories in ROM are simple objects that allow you to compose rich relation
+views specific to your application layer. Every repository can access multiple
+relations that you define and use them to build more complex views.
+
+Repository relations are enhanced with a couple of extra features on top of ROM
+relations:
+
+- Every relation has an auto-generated mapper which turns raw data into simple, immutable structs
+- `Relation#combine` can accept a simple hash defining what other relations should be joined
+- `Relation#combine_parents` automatically joins parents using eager-loading
+- `Relation#combine_children` automatically joins children using eager-loading
+- `Relation#wrap_parent` automatically joins a parent using inner join
+
+### Relation Views
+
+A relation view is a result of some query which returns results specific to your
+application. You can define them using a simple DSL where you specify a name, what
+attributes resulting tuples will have and of course the query itself:
+
+``` ruby
+class Users < ROM::Relation[:sql]
+  view(:by_id, [:id, :name]) do |id|
+    where(id: id).select(:id, :name)
+  end
+
+  view(:listing, [:id, :name, :email, :created_at]) do
+    select(:id, :name, :email, :created_at).order(:name)
+  end
+end
+```
+
+This way we can explicitly define all our relation view that our application will
+depend on. It encapsulates access to application-specific data structures and allows
+you to easily test individual views in isolation.
+
+Thanks to explicit definition of attributes mappers are derived automatically.
+
+### Auto-combine & Auto-wrap
+
+Repository relations support automatic `combine` and `wrap` by using a simple
+convention that every relation defines `for_combine(keys, other)` and `for_wrap(keys, other)`.
+
+You can override the default behavior for combine by defining `for_other_rel_name`
+in example, if you combine tasks with users you can define `Tasks#for_users` and
+this will be used instead of the generic `for_combine`.
+
+### Mapping & Structs
+
+Currently repositories map to `ROM::Struct` by default. In the near future this
+will be configurable.
+
+ROM structs are simple and don't expose an interface to mutate them; however, they
+are not being frozen (at least not yet, we could add a feature for freezing them).
+
+They are coercible to `Hash` so it should be possible to map them further in some
+special cases using ROM mappers.
+
+``` ruby
+class Users < ROM::Relation[:sql]
+  view(:by_id, [:id, :name]) do |id|
+    where(id: id).select(:id, :name)
+  end
+
+  view(:listing, [:id, :name, :email, :created_at]) do
+    select(:id, :name, :email, :created_at).order(:name)
+  end
+end
+
+class UserRepository < ROM::Repository::Base
+  relations :users, :tasks
+
+  def by_id(id)
+    users.by_id(id)
+  end
+
+  def with_tasks(id)
+    users.by_id(id).combine_children(many: tasks)
+  end
+end
+
+rom = ROM.finalize.env
+
+user_repo = UserRepository.new(rom)
+
+puts user_repo.by_id(1).to_a.inspect
+# [#<ROM::Struct[User] id=1 name="Jane">]
+
+puts user_repo.with_tasks.to_a.inspect
+# [#<ROM::Struct[User] id=1 name="Jane" tasks=[#<ROM::Struct[Task] id=2 user_id=1 title="Jane Task">]>, #<ROM::Struct[User] id=2 name="Joe" tasks=[#<ROM::Struct[Task] id=1 user_id=2 title="Joe Task">]>]
+```
+
+### Decorating Structs
+
+Nothing is stopping you from decorating your structs using registered mappers and
+custom decorator models:
+
+``` ruby
+class UserStructMapper < ROM::Mapper
+  register_as :ui_presenter
+  model UI::UserPresenter
+end
+
+user_repo.by_id(1).as(:ui_presenter)
+```
+
+## Limitations
+
+This is an early alpha and works only with rom-sql for now. There are a couple
+improvements waiting to be done in the rom core and then rom-repository will receive
+more love and features.
+
+Stay tuned.
+
+## License
+
+See `LICENSE` file.

data/Rakefile

@@ -0,0 +1,18 @@
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+task default: [:ci]
+
+desc "Run CI tasks"
+task ci: [:spec]
+
+begin
+  require "rubocop/rake_task"
+
+  Rake::Task[:default].enhance [:rubocop]
+
+  RuboCop::RakeTask.new do |task|
+    task.options << "--display-cop-names"
+  end
+rescue LoadError
+end

data/lib/rom-repository.rb

@@ -0,0 +1,2 @@
+require 'rom'
+require 'rom/repository/base'

data/lib/rom/repository/base.rb

@@ -0,0 +1,56 @@
+require 'rom/support/options'
+
+require 'rom/repository/ext/relation'
+
+require 'rom/repository/mapper_builder'
+require 'rom/repository/loading_proxy'
+
+module ROM
+  class Repository < Gateway
+    # Abstract repository class to inherit from
+    #
+    # TODO: rename this to Repository once deprecated Repository from rom core is gone
+    #
+    # @api public
+    class Base # :trollface:
+      include Options
+
+      option :mapper_builder, reader: true, default: proc { MapperBuilder.new }
+
+      # Define which relations your repository is going to use
+      #
+      # @example
+      #   class MyRepo < ROM::Repository::Base
+      #     relations :users, :tasks
+      #   end
+      #
+      #   my_repo = MyRepo.new(rom_env)
+      #
+      #   my_repo.users
+      #   my_repo.tasks
+      #
+      # @return [Array<Symbol>]
+      #
+      # @api public
+      def self.relations(*names)
+        if names.any?
+          attr_reader(*names)
+          @relations = names
+        else
+          @relations
+        end
+      end
+
+      # @api private
+      def initialize(env, options = {})
+        super
+        self.class.relations.each do |name|
+          proxy = LoadingProxy.new(
+            env.relation(name), name: name, mapper_builder: mapper_builder
+          )
+          instance_variable_set("@#{name}", proxy)
+        end
+      end
+    end
+  end
+end

data/lib/rom/repository/ext/relation.rb

@@ -0,0 +1,125 @@
+require 'rom/repository/ext/relation/view_dsl'
+
+module ROM
+  module SQL
+    # A bunch of extensions that will be ported to other adapters
+    #
+    # @api public
+    class Relation < ROM::Relation
+      # @api private
+      def self.inherited(klass)
+        super
+        klass.class_eval do
+          exposed_relations.merge(Set[:columns, :for_combine, :for_wrap])
+
+          defines :attributes
+          attributes({})
+
+          option :attributes, reader: true, default: -> relation { relation.class.attributes }
+        end
+      end
+
+      # Define a relation view with a specific header
+      #
+      # With headers defined all the mappers will be inferred automatically
+      #
+      # @example
+      #   class Users < ROM::Relation[:sql]
+      #     view(:by_name, [:id, :name]) do |name|
+      #       where(name: name)
+      #     end
+      #
+      #     view(:listing, [:id, :name, :email]) do
+      #       select(:id, :name, :email).order(:name)
+      #     end
+      #   end
+      #
+      # @api public
+      def self.view(*args, &block)
+        name, names, relation_block =
+          if block.arity == 0
+            ViewDSL.new(*args, &block).call
+          else
+            [*args, block]
+          end
+
+        attributes[name] = names
+
+        define_method(name, &relation_block)
+      end
+
+      # Return column names that will be selected for this relation
+      #
+      # By default we use dataset columns but first we look at configured
+      # attributes by `view` DSL
+      #
+      # @return [Array<Symbol>]
+      #
+      # @api private
+      def columns
+        self.class.attributes.fetch(name, dataset.columns)
+      end
+
+      # Default methods for fetching combined relation
+      #
+      # This method is used by default by `combine`
+      #
+      # @return [SQL::Relation]
+      #
+      # @api private
+      def for_combine(keys, relation)
+        pk, fk = keys.to_a.flatten
+        where(fk => relation.map { |tuple| tuple[pk] })
+      end
+
+      # Default methods for fetching wrapped relation
+      #
+      # This method is used by default by `wrap` and `wrap_parents`
+      #
+      # @return [SQL::Relation]
+      #
+      # @api private
+      def for_wrap(name, keys)
+        other = __registry__[name]
+
+        inner_join(name, keys)
+          .select(*qualified.header.columns)
+          .select_append(*other.prefix(other.name).qualified.header)
+      end
+
+      # Infer foreign_key name for this relation
+      #
+      # TODO: this should be configurable and handled by an injected policy
+      #
+      # @return [Symbol]
+      #
+      # @api private
+      def foreign_key
+        :"#{Inflector.singularize(name)}_id"
+      end
+    end
+  end
+
+  # TODO: remove this once Relation::Lazy is gone
+  class Relation
+    class Lazy
+      def base_name
+        relation.name
+      end
+
+      def primary_key
+        relation.primary_key
+      end
+
+      def foreign_key
+        relation.foreign_key
+      end
+    end
+
+    class Curried < Lazy
+      def columns
+        relation.attributes.fetch(options[:name], relation.columns)
+      end
+    end
+  end
+end