synchronisable 1.1.5 → 1.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c70006cc02972431afa0d306a1015738489b60c0
-  data.tar.gz: f12f1145a0f3c594e66e689df0e85b333aff056b
+  metadata.gz: 70388e8c1eef4b5cb5e12223a4201d02073248ad
+  data.tar.gz: 829ab2f2ebf18374eaaab7e34b97ca084c494224
 SHA512:
-  metadata.gz: 2f67edbe1fb55314de9f84ef6db56037865fb0a387c67538a35ce14191d9d5e3a59439b35a49587caed9107943b927a027524a6af39260ef87b99cdae49b4760
-  data.tar.gz: 44a3768ad6af8890d1fcc0a2e77cab978196686e8c204b38f5b96cb3a2df4e85a865e64be47d47a5094d9e05043f06a3eb07301f8ff1d4ea116fccd5fcbab153
+  metadata.gz: 3c4b925a4fb1a39e8c7d440fea7803c2303f89b7fad7b951564aa800b18b21d48934691f686e9e112102e005df959792f67d08ba4529687b7e4a84977905e74e
+  data.tar.gz: 7f69d985173f10d17fb3e84474c7b1dc4c0d0d8e8f85eadf9d7cf42a6364aa3072606a0a275a09060a8ec28268998640664019ba2de87f9bae199a239cc58e14

data/README.md

@@ -7,11 +7,21 @@
 
 # Synchronisable
 
-Provides base fuctionality (models, DSL) for AR synchronization
-with external resources (apis, services etc).
+### :construction: this README & docs are work in progress :construction:
 
 ## Overview
 
+Provides base fuctionality for active record models synchronization
+with external resources. The remote source could be anything you like:
+apis, services, site that you gonna parse and steal some data from it.
+
+## Resources
+
+* [Rubygems](https://rubygems.org/gems/synchronisable)
+* [API](http://rdoc.info/github/vyorkin/synchronisable/master/frames)
+* [Bugs](https://github.com/vyorkin/synchronisable/issues)
+* [Development](https://travis-ci.org/vyorkin/synchronisable)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -26,58 +36,195 @@ Or install it yourself as:
 
     $ gem install synchronisable
 
+Optionally, if you are using rails to run an initializer generator:
+
+    $ rails g synchronisable:install
+
+## Rationale
+
+Sometimes we need to sync our domain models (or some part of them)
+with some kind of remote source. Its great if you can consume a well-done RESTful api
+that is pretty close to you local domain models.
+But unfortunately the remote data source could be just anything.
+
+Actually this gem was made to consume data coming from a site parser :crying_cat_face:
+
+Examples of the usage patterns are shown below.
+You can find more by looking at the [dummy app](https://github.com/vyorkin/synchronisable/tree/master/spec/dummy/app)
+[models](https://github.com/vyorkin/synchronisable/tree/master/spec/dummy/app/models) and
+[synchronizers](https://github.com/vyorkin/synchronisable/tree/master/spec/dummy/app/synchronizers).
+
+## Features
+
+* Attribute mapping, `unique_id`
+* Associations sync + `:includes` option to specify (restrict)
+  an association tree to be synchronized
+* `before` and `after` callbacks to hook into sync process
+* ???
+
+## Configuration
+
+For rails users there is a well-documented initializer.
+Just run `rails g synchronisable:install` and you'll be fine.
+
+Non-rails users can do so by using provided
+`ActiveSupport::Configurable` interface. So here is the default settings:
+
+```ruby
+Synchronisable.configure do |config|
+  # Logging configuration
+  #
+  # Default logger fallbacks to `Rails.logger` if available, otherwise
+  # `STDOUT` will be used for output.
+  #
+  config.logging = {
+    :logger   => defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
+    :verbose  => true,
+    :colorize => true
+  }
+
+  # If you want to restrict synchronized models.
+  # By default it will try to sync all models that have
+  # a `synchronisable` dsl instruction.
+  #
+  config.models = %w(Foo Bar)
+end
+```
+
 ## Usage
 
-For examples we'll be using a well-known domain with posts & comments
+Imagine a situation when you have to periodically get data from
+some remote source and store it locally.
+Basically the task is to create local records if they don't exist
+and update their attributes otherwise.
+
+### Gateways
+
+Thing that provides an access to an external system or resource
+is called [gateway](http://martinfowler.com/eaaCatalog/gateway.html).
+You can take a look at the base [gateway](https://github.com/vyorkin/synchronisable/blob/master/lib/synchronisable/gateway.rb)
+class to get a clue what does it mean in terms of this gem
+(btw fetching data from a remote source is not a purpose of this gem).
+
+The main idea is that gateway implementation class has only 2 methods:
+
+* `fetch(params = {})` – returns an array of hashes, each hash contains
+   an attributes that should be (somehow) mapped over your target model.
+* `find(params)` – returns a single hash with remote attributes.
+  `params` here is only to have a choice between representing a single
+   or a composite identity.
+
+### Models and synchronizers
+
+The first step is to declare that your active record model is synchronizable.
+You can do so by using corresponding `synchronisable` dsl instruction,
+that optionally takes a synchonizer class to be used.
+You should only specify it when the name can't be figured out
+by the following convention: `ModelSynchronizer`.
+So for example here we have a Tournament that has many Stages:
 
 ```ruby
-class Post < ActiveRecord::Base
-  has_many :comments
+class Tournament < ActiveRecord::Base
+  has_many :stages
 
   synchronisable
 end
 
-class Comment < ActiveRecord::Base
-  belongs_to :post
+class Stage < ActiveRecord::Base
+  belongs_to :tournament
 
-  synchronisable MyCommentSynchronizer
+  synchronisable
 end
 ```
 
-As you can see above the first step is to declare your models to be
-synchronisable. You can do so by using corresponding dsl instruction,
-that optionally takes a synchonizer class to be used. Actually,
-the only reason to specify it its when it has a name, that can't be figured out
-by the following convention: `ModelSynchronizer`.
-
-After that you should define your model synchronizers
+Lets define synchronizers:
 
 ```ruby
-class PostSynchronizer < Synchronisable::Synchronizer
-  remote_id :p_id
+class TournamentSynchronizer < Synchronisable::Synchronizer
+  has_many :stages
 
+  remote_id :tour_id
+  unique_id { |attrs| attrs[:name] }
+
+  mappings(
+    :eman       => :name,
+    :eman_trohs => :short_name,
+    :gninnigeb  => :beginning,
+    :gnidge     => :ending,
+    :tnerruc_si => :is_current
+  )
+
+  only :name, :beginning, :ending
+
+  gateway TournamentGateway
+end
+
+class StageSynchronizer < Synchronisable::Synchronizer
+  has_many :matches
+
+  remote_id :stage_id
+
+  mappings(
+    :tour_id   => :tournament_id,
+    :gninnigeb => :beginning,
+    :gnidge    => :ending,
+    :eman      => :name,
+    :rebmun    => :number
+  )
+
+  except :ignored_1, :ignored_2
+
+  gateway StageGateway
+
+  before_sync do |source|
+    source.local_attrs[:name] != 'ignored'
+  end
+end
+```
+
+### Gateways vs `fetch` & `find` in synchronizers
+
+TDOO: Blah blah blah... Need to describe the difference & use cases.
+
+### Blah blah
+
+### Blah blah
+
+```ruby
+class TournamentSynchronizer < Synchronisable::Synchronizer
   mappings(
     :t => :title,
     :c => :content
   )
 
+  remote_id :p_id
+
+  # Local attributes to ignore.
+  # These will not be set on your local record.
   except :ignored_attr1, :ignored_attr42
 
+  # Declares that we want to sync comments after syncing this model.
+  # The resulting hash with remote attributes should contain `comment_ids`
   has_many :comments
 
+  # Method that will be used to fetch all of the remote entities
   fetch do
-    # return array of hashes with
-    # remote entity attributes
+    # Somehow get and return an array of hashes with remote entity attibutes
+    [
+      { t: 'first', c: 'i am the first post' },
+      { t: 'second', c: 'content of the second post'  }
+    ]
   end
 
+  # This method should return only one hash for the given id
   find do |id|
-    # return a hash with
-    # with remote entity attributes
+    # return a hash with with remote entity attributes
+    # ...
   end
 
-  # Hooks/callbacks
-
+  #
   before_record_sync do |source|
+    # return false if you want to skip syncing of this particular record
     # ...
   end
 
@@ -95,6 +242,7 @@ class PostSynchronizer < Synchronisable::Synchronizer
 
   before_sync do |source|
     # ...
+    # return false if you want to skip syncing of this particular record
   end
 
   after_sync do |source|
@@ -102,6 +250,8 @@ class PostSynchronizer < Synchronisable::Synchronizer
   end
 end
 
+
+
 class MyCommentSynchronizer < Synchronisable::Synchronizer
   remote_id :c_id
 

data/lib/synchronisable/configuration.rb

@@ -0,0 +1,21 @@
+module Synchronisable
+  class Configuration
+    include ActiveSupport::Configurable
+
+    config_accessor :models do
+      {}
+    end
+    config_accessor :logging do
+      default_logger = -> { Logger.new(STDOUT) }
+      rails_logger   = -> { Rails.logger || default_logger.() }
+
+      logger = defined?(Rails) ? rails_logger.() : default_logger.()
+
+      {
+        :logger   => logger,
+        :verbose  => true,
+        :colorize => true
+      }
+    end
+  end
+end

data/lib/synchronisable/gateway.rb

@@ -4,7 +4,7 @@ module Synchronisable
       not_implemented :fetch
     end
 
-    def find(id)
+    def find(params)
       not_implemented :find
     end
 

data/lib/synchronisable/helper/logging.rb

@@ -10,7 +10,7 @@ module Synchronisable
 
       %i(verbose colorize).each do |name|
         define_method("#{name}_logging?".to_sym) do
-          Synchronisable.logging[name]
+          Synchronisable.config.logging[name]
         end
       end
 

data/lib/synchronisable/model.rb

@@ -33,6 +33,12 @@ module Synchronisable
         class_attribute :synchronizer
         has_one :import, as: :synchronisable, class_name: 'Synchronisable::Import'
 
+        scope :without_import, -> {
+          includes(:import)
+            .where(imports: { synchronisable_id: nil })
+            .references(:imports)
+        }
+
         set_defaults(args)
       end
 

data/lib/synchronisable/source.rb

@@ -1,5 +1,3 @@
-require 'pry-byebug'
-
 module Synchronisable
   # TODO: Massive refactoring needed
 

data/lib/synchronisable/synchronizer.rb

@@ -27,7 +27,7 @@ module Synchronisable
       source.try(:with_indifferent_access)
     }
 
-    # Attributes that will be ignored.
+    # Attributes to ignored.
     attribute :except, converter: SYMBOL_ARRAY_CONVERTER
 
     # The only attributes that will be used.
@@ -39,7 +39,7 @@ module Synchronisable
 
     # Logger that will be used during synchronization
     # of this particular model.
-    attribute :logger, default: -> { Synchronisable.logging[:logger] }
+    attribute :logger, default: -> { Synchronisable.config.logging[:logger] }
 
     # Gateway to be used to get the remote data
     #

data/lib/synchronisable/version.rb

@@ -2,7 +2,7 @@ module Synchronisable
   module VERSION
     MAJOR = 1
     MINOR = 1
-    PATCH = 5
+    PATCH = 6
     SUFFIX = nil
 
     STRING = [MAJOR, MINOR, PATCH, SUFFIX].compact.join('.')

data/lib/synchronisable.rb

@@ -11,44 +11,39 @@ require 'active_support/concern'
 require 'synchronisable/bootstrap/i18n'
 
 require 'synchronisable/version'
+require 'synchronisable/configuration'
 require 'synchronisable/models/import'
 require 'synchronisable/synchronizer'
 require 'synchronisable/model'
 require 'synchronisable/gateway'
 
-
 module Synchronisable
-  include ActiveSupport::Configurable
-
-  config_accessor :models do
-    {}
+  def self.config
+    @configuration ||= Configuration.new
   end
-  config_accessor :logging do
-    default_logger = -> { Logger.new(STDOUT) }
-    rails_logger   = -> { Rails.logger || default_logger.() }
-
-    logger = defined?(Rails) ? rails_logger.() : default_logger.()
 
-    {
-      :logger   => logger,
-      :verbose  => true,
-      :colorize => true
-    }
+  def self.configure
+    yield config
   end
 
   # Syncs models that are defined in {Synchronisable#models}
   #
-  # @param models [Array] array of models that should be synchronized.
-  #   This take a precedence over models defined in {Synchronisable#models}.
-  #   If this parameter is not specified and {Synchronisable#models} is empty,
-  #   than it will try to sync only those models which have a corresponding synchronizers
+  # @overload sync(models, options)
+  #   @param models [Array] array of models that should be synchronized.
+  #     This take a precedence over models defined in {Synchronisable#models}.
+  #     If this parameter is not specified and {Synchronisable#models} is empty,
+  #     than it will try to sync only those models which have a corresponding synchronizers
+  #   @param options [Hash] options that will be passed to controller
+  # @overload sync(models)
+  # @overlaod sync(options)
   #
   # @return [Array<[Synchronisable::Context]>] array of synchronization contexts
   #
   # @see Synchronisable::Context
-  def self.sync(*models)
-    source = source_models(models)
-    source.map(&:sync)
+  def self.sync(*args)
+    options = args.extract_options!
+    source = source_models(args)
+    source.map { |model| model.sync(options) }
   end
 
   private
@@ -59,7 +54,7 @@ module Synchronisable
   end
 
   def self.default_models
-    models.map(&:safe_constantize).compact
+    config.models.map(&:safe_constantize).compact
   end
 
   def self.find_models

data/spec/synchronisable/synchronisable_spec.rb

@@ -9,7 +9,7 @@ describe Synchronisable do
     describe 'models specified in configuration' do
       context 'only Team and Match' do
         before :all do
-          Synchronisable.models = %w(Match Team)
+          Synchronisable.config.models = %w(Match Team)
         end
 
         it { is_expected.to change { Match.count }.by(1) }
@@ -22,7 +22,7 @@ describe Synchronisable do
 
       context 'all' do
         before :all do
-          Synchronisable.models = %w(
+          Synchronisable.config.models = %w(
             Tournament Team
             Match MatchPlayer Player
           )
@@ -40,7 +40,7 @@ describe Synchronisable do
 
       context 'when models setting is overriden in method call' do
         before :all do
-          Synchronisable.models = %w(Team Match)
+          Synchronisable.config.models = %w(Team Match)
         end
 
         subject do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: synchronisable
 version: !ruby/object:Gem::Version
-  version: 1.1.5
+  version: 1.1.6
 platform: ruby
 authors:
 - Vasiliy Yorkin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-22 00:00:00.000000000 Z
+date: 2014-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord