hexx-storage 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d74c167834036021a713089804dad4d1ee5fb26a
+  data.tar.gz: 3c6a2ea6a487df2ce141c48358868e446cfc0dd8
+SHA512:
+  metadata.gz: b7297c164f8a7596015313b3ead43c89043814732e29126c585f4ad8e45089d447d87a799fcb05e6321b9bfb9d03959719d2eceb650a7c02b4f781536f64bed0
+  data.tar.gz: 892e9681876e62f70f87678fcf1859b44a8fa4180bb5145d6f65927e9b4b98d4cee09d3c3875eb72503d19d685e8d7e5f790997c2f950fcfeb9aeceeec2b393d

data/.coveralls.yml

@@ -0,0 +1,2 @@
+---
+service_name: travis-ci

data/.gitignore

@@ -0,0 +1,9 @@
+*.gem
+*.lock
+.bundle/
+.yardoc/
+coverage/
+doc/
+log/
+pkg/
+tmp/

data/.metrics

@@ -0,0 +1,9 @@
+# Settings for metric_fu and its packages are collected in the `config/metrics`
+# and loaded by the Hexx::Suit::Metrics::MetricFu.
+
+begin
+  require "hexx-suit"
+  Hexx::Suit::Metrics::MetricFu.load
+rescue LoadError
+  puts "The 'hexx-suit' gem is not installed"
+end

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,2 @@
+---
+inherit_from: "./config/metrics/rubocop.yml"

data/.travis.yml

@@ -0,0 +1,12 @@
+---
+language: ruby
+before_script:
+  - psql -c 'create database rom;' -U postgres -w
+bundler_args: --without metrics
+script: rake test:coverage:run
+rvm:
+  # - '2.0' # doesn't support "def foo(bar:); end"
+  - '2.1'
+  - '2.2'
+  # - rbx-2 # doesn't support refinements
+  # - jruby-9.0.0.0.pre1 # doesn't support refinements

data/.yardopts

@@ -0,0 +1,3 @@
+--asset LICENSE
+--exclude lib/hexx/storage/version.rb
+--output doc/api

data/Gemfile

@@ -0,0 +1,12 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :metrics do
+  gem "hexx-suit", "~> 2.2" if RUBY_ENGINE == "ruby"
+end
+
+group :test do
+  gem 'pg', platforms: [:mri, :rbx]
+  gem 'pg_jruby', platforms: :jruby
+end

data/Guardfile

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+guard :rspec, cmd: "bundle exec rspec" do
+
+  watch(%r{^lib/hexx/(.+)\.rb$}) do |m|
+    "spec/tests/#{ m[1] }_spec.rb"
+  end
+
+  watch(%r{^spec/.+_spec\.rb$})
+
+  watch("lib/hexx-storage.rb")  { "spec" }
+  watch("spec/spec_helper.rb")  { "spec" }
+
+end # guard :rspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2015 Andrew Kozin (nepalez), andrew.kozin@gmail.com
+
+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,351 @@
+Hexx::Storage
+=============
+
+[![Gem Version](https://img.shields.io/gem/v/hexx-storage.svg?style=flat)][gem]
+[![Build Status](https://img.shields.io/travis/nepalez/hexx-storage/master.svg?style=flat)][travis]
+[![Dependency Status](https://img.shields.io/gemnasium/nepalez/hexx-storage.svg?style=flat)][gemnasium]
+[![Code Climate](https://img.shields.io/codeclimate/github/nepalez/hexx-storage.svg?style=flat)][codeclimate]
+[![Coverage](https://img.shields.io/coveralls/nepalez/hexx-storage.svg?style=flat)][coveralls]
+[![Inline docs](http://inch-ci.org/github/nepalez/hexx-storage.svg)][inch]
+
+[codeclimate]: https://codeclimate.com/github/nepalez/hexx-storage
+[coveralls]: https://coveralls.io/r/nepalez/hexx-storage
+[gem]: https://rubygems.org/gems/hexx-storage
+[gemnasium]: https://gemnasium.com/nepalez/hexx-storage
+[travis]: https://travis-ci.org/nepalez/hexx-storage
+[inch]: https://inch-ci.org/github/nepalez/hexx-storage
+
+The module provides additional sugar for setting [sweety ROM] from yml.
+
+* [Synopsis](#synopsis)
+* [Extended example](#extended-example)
+* [Installation](#installation)
+* [Compatibility](#compatibility)
+* [MIT LICENSE](LICENSE)
+
+[sweety ROM]: http://rom-rb.org
+
+Synopsis
+--------
+
+Providing some settings exist:
+
+```yaml
+# application_path/config/rom/my_gem.yml
+---
+test: # required environment level
+  foo: # required repository name level
+    adapter: :memory
+  bar:
+    adapter: :memory
+    log:     "tmp/logs/my_gem/test/bar.log"
+production:
+  foo:
+    adapter:  :memory
+  bar:
+    adapter:  :sql
+    uri:      "postgres://localhost/rom"
+    user:     "foo"
+    password: "bar"
+    log:      "tmp/logs/my_gem/bar.log"
+```
+
+Load them to the storage:
+
+```ruby
+require "hexx-storage"
+
+storage = Hexx::Storage.setup
+
+# root path of the application than carries settings
+storage.root = "application_path"
+# load settings from file, relative to that root
+storage.load "config/rom/my_gem.yml", env: :production
+# add migrations paths to some repositories
+storage[:bar].migrations = "my_gem/db/migrations/bar"
+```
+
+And check the results:
+
+```ruby
+# final settings for the ROM.setup
+storage.settings
+# => {
+#      foo: [:memory, "foo"],
+#      bar: [
+#        :sql,
+#        [
+#          #<Sequel::PG::Database: ...>,
+#          migrator: #<ROM::SQL::Migration::Migrator ...>
+#        ]
+#      ]
+#    }
+```
+
+Some more details:
+
+```ruby
+# names of repositories:
+storage.keys # => [:foo, :bar]
+
+# uri-s
+storage.values.map(&:uri)
+# => [nil, "postgres://localhost/rom"]
+
+# additional options (except for adapter, uri and log)
+storage[:bar].options
+# => { user: "foo", password: "bar" }
+
+# loggers (from established root and log)
+storage[:foo].logger
+# => nil (no logger is set)
+storage[:bar].logger
+# => #<Logger
+#      @logdev= <Logger::LogDevice
+#        @filename="application_path/tmp/logs/my_gem/bar.log"
+#      >
+#    >
+```
+
+Settings specific for `:sql` adapter:
+
+```ruby
+# established Sequel connections
+storage[:foo].conn
+# => nil (adapter is not the :sql)
+storage[:bar].conn
+# => #<Sequel::PG::Database: "postgres://localhost/rom">
+
+# if the logger is set, it is authomatically added to the connection
+storage[:bar].conn.loggers
+# => [#<Logger ...>]
+
+# migrators
+storage[:foo].migrator
+# => nil (adapter is not the :sql)
+storage[:bar].migrator
+# => #<ROM::SQL::Migration::Migrator 
+#      @connection=#<Sequel::PG::Database: "postgres://localhost/rom">
+#      @path="my_gem/db/migrations/bar"
+#    >
+```
+
+Extended Example
+----------------
+
+Below is example of setings for the `my_gem` gem used inside the application. 
+
+The example consists of 3 parts:
+* [MyGem](#mygem) the ROM is set up for
+* [Application](#application) the ROM is set up from
+* [Dummy App](#dummy-app) for testing the gem
+
+### MyGem
+
+The loader:
+
+```ruby
+# my_gem_path/lib/my_gem.rb
+module MyGem
+  # loads patches (refinements) to external classes (Ruby core, stdlib etc.)
+  require_relative "my_gem/patches"
+  # loads and initializes the gem's settings
+  require_relative "my_gem/settings"
+  # loads the core part of the domain (value objects, entities, policies etc.),
+  # that don't use the persistency layer
+  require_relative "my_gem/core"
+  # loads the ROM-based persistency layer
+  # (sets ROM up with relations, mappers, and commands)
+  require_relative "my_gem/storage"
+  # loads the domain API (service objects that backs on both the domain core,
+  # and the persistency layer)
+  require_relative "my_gem/api"
+end
+```
+
+The `Settings` provides a singleton object to collect all module settings, including the storage and other external dependencies.
+
+After definition it loads the initializer, provided by an [application](#application).
+
+```ruby
+# my_gem_path/lib/my_gem/settings.rb
+require "hexx-storage"
+
+module MyGem
+  module Settings
+    include Singleton
+
+    def self.configure
+      yield self if block_given?
+    end
+
+    def self.[](name)
+      send_public name
+    end
+
+    def storage
+      @storage ||= Hexx::Storage.setup
+    end
+  end
+  
+  # Initializes the dependencies from the initializer, provided by application.
+  require File.join ENV["PATH_TO_INITIALIZERS"], "my_gem.rb"
+end
+```
+
+The persistency layer backs on the `ROM` module, whose settings has been initialized before.
+
+```ruby
+# my_gem_path/lib/my_gem/storage.rb
+
+require "rom"
+
+module MyGem
+  # Takes storage from the initialized settings
+  storage = Settings[:storage]
+
+  # Sets path to local migrations (that's why they are assigned separately)
+  # (no need to copy migrations to the application, like Rails does)
+  storage[:default].migrations = File.join "storage/migrations"
+
+  # Sets ROM up with the initialized storage settings
+  ROM.setup(storage.settings)
+
+  # Loads ROM relations, commands and mappers, that depends from
+  # value objects and entities, that are loaded as parts of the
+  # core part of the module (see the loading sequence in the loader).
+
+  # ...
+
+  # Finalizes the ROM and sets established loggers to its repositories
+  ROM.finalize
+  ROM.env.repositories[:default].use_logger storage[:default].logger
+
+  # Memoizes the ROM environment that can be reset by the application
+  STORAGE = ROM.env
+end
+```
+
+The `RSpec` helper loads `my_gem` inside the
+[dummy application](#the-dummy-app-for-the-mygem):
+
+```ruby
+# my_gem_path/spec/spec_helper.rb
+require "dummy/lib/dummy"
+```
+
+### Application
+
+The loader:
+
+```ruby
+# application_path/lib/application.rb
+
+# The application knows the :sql adapter will be used
+require "rom-sql"
+
+# Sets path to initializers
+ENV["PATH_TO_INITIALIZERS"] = File.expand_path "../config/initializers"
+
+# Gives control to the gem loader
+require "my_gem"
+```
+
+The `my_gem` initializer inside the application:
+
+```ruby
+# application_path/config/initializers/my_gem.rb
+MyGem::Settings.configure do |config|
+  config.storage.root = File.join ".."
+  config.storage.load "config/rom/my_gem.yml", env: ENV["CURRENT_ENV"]
+end
+```
+
+The `my_gem` storage's settings inside the application:
+
+```yaml
+# application_path/config/rom/my_gem.yml
+---
+test:
+  default:
+    adapter: :memory
+    uri:     "my_gem"
+    log:     "tmp/logs/test/my_gem.test.log"  # relative to application root
+production:
+  default:
+    adapter: :sql
+    uri:     "postgres://localhost/rom" # whatever
+    log:     "tmp/logs/production/my_gem.log" # relative to application root
+```
+
+### Dummy App
+
+The loader:
+
+```ruby
+# my_gem_path/spec/dummy/lib/dummy.rb
+
+# Sets initializers folder relative to the Dummy
+ENV["PATH_TO_INITIALIZERS"] = File
+  .expand_path "../spec/dummy/config/initializers"
+
+require "my_gem"
+```
+
+The `MyGem` initializer:
+
+```ruby
+# my_gem_path/spec/dummy/config/initializers/my_module.rb
+MyGem::Settings.configure do |config|
+  config.storage.root = File.join "../spec/dummy"
+  config.storage.load "config/rom/my_gem.yml", env: :test
+end
+```
+
+The `ROM` storage settings for `MyGem`:
+
+```yaml
+# my_gem_path/spec/dummy/config/rom/my_gem.yml
+---
+test:
+  default:
+    adapter: :memory
+    log:     "../../tmp/logs/test.log" # relative to the Dummy root
+```
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+```ruby
+# Gemfile
+gem "hexx-storage", git: "https://github.com/nepalez/hexx-storage"
+```
+
+Then execute:
+
+```
+bundle
+```
+
+Compatibility
+-------------
+
+Tested under MRI 2.1+
+
+Limitations:
+
+* MRI 2.0 doesn't support syntax `def foo(bar:)`
+* both JRuby and Rubinius don't support [refinements]
+
+Uses [RSpec] 3.0+ for testing and [hexx-suit] for dev/test tools collection.
+
+[refinements]: http://ruby-doc.org/core-2.1.1/doc/syntax/refinements_rdoc.html
+[RSpec]: http://rspec.info/
+[hexx-suit]: http://github.com/nepalez/hexx-suit
+
+License
+-------
+
+See the [MIT LICENSE](LICENSE).