synced 0.0.11 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 90439e42a4207f1d7fb304492d01dbda6ca3c519
-  data.tar.gz: df7f7f52f5ae49f7c8dd30178a6bb6ec07c4e723
+  metadata.gz: cdb428e328ca8da932f79510c83a0605cc220bcc
+  data.tar.gz: 70b0d79a78f4ed66802c5600dc18d5f5fa49d2d8
 SHA512:
-  metadata.gz: 0648b7cec0c209758e6992d59377beeee9a3fdb80157013025c2ba9af4155e4acad635f0e2e5ea11490ceb8db3723328347370c76502f6222caeed1877923e21
-  data.tar.gz: 9b9697a81e6056b27d402f8dd130af09f3c08c9f66babd7782843c3e661c53fc9a3abd397a964b50b2a2b2180171209a61a181f0a6d51c1c3323cb880fe5a651
+  metadata.gz: c6e6dfdc5295494cbeca0f90f02dfe17031ccc34c730f863d2c36b1a3fcf2cc27bdec9b39bc000832ad230bf93b50f073fe224a8ad24978e5dd97c5354add5e2
+  data.tar.gz: d4e6b75d4ddcd2580cba514ddfbf83384949868208e3a3414c9ba5f264a86c8989d0fa43b1fecc1c8a005e0b86b8e25503d2264b73a88f8492afaed1c28ffada

data/README.md

@@ -6,34 +6,41 @@
 Synced is a Rails Engine that helps you keep local models synchronized with
 their BookingSync representation.
 
-Note: This synchronization is in one way only, from BookingSync to your
-application. If you want to do a 2 way synchronization, you will need to
-implement it yourself using
-[BookingSync-API](https://github.com/BookingSync/bookingsync-api)
+It decreases time needed to fetch data from BookingSync API. If given endpoint
+supports `updated_since` parameter, Synced will first perform a full
+synchronization and then every next synchronization will only synchronize
+added/changed/deleted objects since last synchronization.
 
 ## Requirements
 
 This engine requires Rails `>= 4.0.0` and Ruby `>= 2.0.0`.
 
-## Documentation
-
-[API documentation is available at rdoc.info](http://rdoc.info/github/BookingSync/synced/master/frames).
-
 ## Installation
 
-Synced works with BookingSync API 0.0.17 onwards, Rails 4.0 onwards and Ruby
-2.0 onwards. To get started, add it to your Gemfile with:
+To get started, add it to your Gemfile with:
 
 ```ruby
 gem 'synced'
 ```
+and run `bundle install`
+
+## Basic usage
+
+Assume we want to create an application displaying rentals from multiple
+BookingSync accounts and we want to synchronize rentals to make it snappy
+and traffic efficient.
+
+We will surely have `Rental` and `Account` models. Where `Account` will have
+`BookingSync::Engine::Account` mixin and thus respond to `api` method.
 
-Generate a migration to add Synced fields for the model you want to synchronize:
+First generate a migration to add synced fields to the model.
+These fields will be used for storing data from the API.
 
 Example:
+
 ```console
 rails g migration AddSyncedFieldsToRentals synced_id:integer:index \
-  synced_data:text synced_updated_at:datetime
+  synced_data:text synced_all_at:datetime
 ```
 
 and migrate:
@@ -42,82 +49,155 @@ and migrate:
 rake db:migrate
 ```
 
-And `synced` statement to the model you want to keep in sync.
-
-Example:
+Add `synced` statement to the model you want to keep in sync and add `api`
+method which return instance of `BookingSync::API::Client` used for fetching
+data.
 
 ```ruby
 class Rental < ActiveRecord::Base
   synced
+  belongs_to :account
 end
 ```
 
-Run synchronization with given remote rentals
-
 Example:
 
+Synchronize rentals for given account.
+
 ```ruby
-Rental.synchronize(remote: remote_rentals)
+Rental.synchronize(scope: account)
 ```
 
-Run rentals synchronization in website scope
-
-Example:
+Now rentals details fetched from the API are accessible through `synced_data`
+method.
 
 ```ruby
-Rental.synchronize(remote: remote_rentals, scope: website)
+rental = account.rentals.first
+rental.synced_data.bedrooms # => 4
+rental.synced_data.rental_type # => "villa"
 ```
 
-## Custom fields for storing remote object data.
-
-By default synced stores remote object in the following db columns.
+## Synced database fields
 
-    `synced_id` - ID of the remote object
-    `synced_data` - Whole remote object is serialized into this attribute
-    `synced_all_at` - Synchronization time of the local object when using
-                      updated_since param
+Option name          | Default value    | Description                             | Required |
+---------------------|------------------|-----------------------------------------|----------|
+`:id_key`            | `:synced_id`     | ID of the object fetched from the API   | YES      |
+`:data_key`          | `:synced_data`   | Stores data fetched from the API        | NO       |
+`:synced_all_at_key` | `:synced_all_at` | Stores time of the last synchronization | NO       |
 
-You can configure your own fields in `synced` declaration in your model.
+Custom fields name can be configured in the `synced` statement of your model:
 
-```
+```ruby
 class Rental < ActiveRecord::Base
-  synced id_key: :remote_id, data_key: :remote_data, synced_all_at_key: :remote_all_synced_at
+  synced id_key: :remote_id, data_key: :remote_data,
+    synced_all_at_key: :remote_all_synced_at
 end
 ```
 
 ## Local attributes
 
-All remote data is stored in `synced_data`, however sometimes it's useful to have some attributes directly in your model. You can use `local_attributes` for that.
+Whole remote data is stored in `synced_data` column, however sometimes it's
+useful (for example for sorting) to have some attributes directly in your model.
+You can use `local_attributes` to achieve it:
 
-```
+```ruby
 class Rental < ActiveRecord::Base
   synced local_attributes: [:name, :size]
 end
 ```
 
-This assumes that model has name and size attributes. On every sychronization these two attributes will be assigned with value of `remote_object.name` and `remote_object.size` appropriately.
+This assumes that model has `name` and `size` attributes.
+On every synchronization these two attributes will be assigned with value of
+ `remote_object.name` and `remote_object.size` appropriately.
 
-## Disabling synchronization for selected fields.
+### Local attributes with custom names
 
-In some cases you only need one attribute to be synchronized and nothing more.
-By default even when using local_attributes, whole remote object will be
-saved in the `synced_data` and its updated_at in the `synced_all_at`.
-This may take additonal space in the database.
-In order to disable synchronizing these fields, set their names in the `synced` declaration to nil, as in the below example:
+If you want to store attributes from remote object under different name, you
+need to pass your own mapping hash to `synced` statement.
+Keys are local attributes and values are remote ones. See below example:
 
+```ruby
+class Rental < ActiveRecord::Base
+  synced local_attributes: { headline: :name, remote_size: :size }
+end
 ```
+
+During synchronization to local attribute `headline` will be assigned value of
+`name` attribute of the remote object and to the local `remote_size` attribute
+will be assigned value of `size` attribute of the remote object.
+
+### Local attributes with mapping blocks
+
+If you want to convert an attributes value during synchronization you can
+pass a block as value in the mapping hash. Block will receive remote object
+as the only argument.
+
+```ruby
+class Rental < ActiveRecord::Base
+  synced local_attributes: { headline: ->(rental) { rental.headline.downcase } }
+end
+```
+
+### Local attributes with mapping modules
+
+Converting remote object's values with blocks is really easy, but when you get
+more attributes and longer code in the blocks they might become quite complex
+and hard to read. In such cases you can use a mapper module.
+Remote object will be extended with it.
+
+```ruby
+class Rental < ActiveRecord::Base
+  module Mapper
+    def downcased_headline
+      headline.downcase
+    end
+  end
+  synced mapper: Mapper, local_attributes: { headline: :downcased_headline }
+end
+```
+
+If you want to define Mapper module after the synced directive, you need to
+pass Mapper module inside a block to avoid "uninitialized constant" exception.
+
+```ruby
 class Rental < ActiveRecord::Base
-  synced data_key: nil, synced_all_at_key: nil
+  synced mapper: -> { Mapper },
+    local_attributes: { headline: :downcased_headline }
+  module Mapper
+  end
 end
 ```
 
+## Partial updates (using updated since parameter)
+
+Partial updates mean that first synchronization will copy all of the remote
+objects into local database and next synchronizations will sync only
+added/changed and removed objects. This significantly improves synchronization
+time and saves network traffic.
+
+In order to enable it add timestamp column named `synced_all_at` to your
+database. Synced will automatically detect it.
+
+NOTE: In order it to work, given endpoint needs to support updated_since
+parameter. Check [API documentation](http://docs.api.bookingsync.com/reference/)
+for given endpoint.
+
+## Disabling saving whole synced_data
+
+If you don't need whole remote object to be stored in local object skip
+creating `synced_data` column in the database or set `synced_data_key: nil`.
+
+If you don't want to synchronize only added/changed or deleted objects but all
+objects every time, don't create `synced_all_at` column in the database or set
+`synced_all_at: false` in the synced statement.
+
 You cannot disable synchronizing `synced_id` as it's required to match local
 objects with the remote ones.
 
 ## Associations
 
-It's possible to synchronize objects together with it's associations. For that
-you need to
+It's possible to synchronize objects together with it's associations. Meaning
+local associated objects will be created. For that you need to:
 
   1. Specify associations you want to synchronize within `synced`
     declaration of the parent model
@@ -139,6 +219,109 @@ Then run synchronization of the parent objects. Every of the remote_locations
 objects needs to respond to `remote_location[:photos]` from where data for
 photos association will be taken.
 
+```ruby
+Location.synchronize
+```
+
+NOTE: It assumes that local association `photos` exists in `Location` model.
+
+## Including associations in synced_data
+
+When you need associated data available in the local object, but you don't
+need it to be a local association, you can use `include:` option in model or
+synchronize method.
+
+```ruby
+class Location < ActiveRecord::Base
+  synced include: :photos
+end
+
+Location.first.synced_data.photos # => [{id: 1}, {id: 2}]
+```
+
+You can also specify `include:` option in synchronize method. In this case it
+will overwrite `include:` from the model.
+
+```ruby
+Location.synchronize(include: :addresses)
+```
+
+## Synchronization of given remote objects
+
+By default synced will fetch remote objects using BookingSync::API::Client
+but in some cases you might want to provide own list of remote objects to
+synchronize. In order to do that provide them as `remote:` option to synchronize
+method.
+
 ```ruby
 Location.synchronize(remote: remote_locations)
 ```
+
+NOTE: Partial updates are disabled when providing remote objects.
+
+## Removing local objects
+
+By default synchronization will not delete any local objects which are removed
+on the API side. In order to remove local objects removed on the API, specify
+`remove: true` in the model or as an option to synchronize method.
+
+```ruby
+class Photo < ActiveRecord::Base
+  synced remove: true
+end
+```
+
+Option `remove:` passed to `Photo.synchronize` method will overwrite
+configuration in the model.
+
+For objects which need to be removed `:destroy_all` is called.
+If model has `canceled_at` column, local objects will be canceled with
+`:cancel_all` class method. You can force your own class method to be called on
+the local objects which should be removed by passing it as an symbol.
+
+```ruby
+class Photo < ActiveRecord::Base
+  synced remove: :mark_as_outdated
+
+  def self.mark_as_outdated
+    all.update_attributes(outdated: true)
+  end
+end
+```
+
+## Selecting fields to be synchronized
+
+Very often you don't need whole object to be fetched and stored in local
+database but only several fields. You can specify which fields should be fetched
+and stored with `fields:` option.
+
+```ruby
+class Photo < ActiveRecord::Base
+  synced fields: [:name, :url]
+end
+```
+
+This can be overwritten in synchronize method.
+
+```ruby
+Photo.synchronize(fields: [:name, :size])
+```
+
+## Synced configuration options
+
+Option name          | Default value    | Description                                                                       | synced | synchronize |
+---------------------|------------------|-----------------------------------------------------------------------------------|--------|-------------|
+`:id_key`            | `:synced_id`     | ID of the object fetched from the API                                             | YES    | NO          |
+`:data_key`          | `:synced_data`   | Object fetched from the API                                                       | YES    | NO          |
+`:synced_all_at_key` | `:synced_all_at` | Time of the last synchronization                                                  | YES    | NO          |
+`:associations`      | `[]`             | [Sync remote associations to local ones](#associations)                           | YES    | NO          |
+`:local_attributes`  | `[]`             | [Sync remote attributes to local ones](#local-attributes)                         | YES    | NO          |
+`:mapper`            | `nil`            | [Module used for mapping remote objects](#local-attributes-with-mapping-modules)  | YES    | NO          |
+`:remove`            | `false`          | [If local objects should be removed when deleted on API](#removing-local-objects) | YES    | YES         |
+`:include`           | `[]`             | [An array of associations to be fetched](#including-associations-in-synced_data)  | YES    | YES         |
+`:fields`            | `[]`             | [An array of fields to be fetched](#selecting-fields-to-be-synchronized)          | YES    | YES         |
+`:remote`            | `nil`            | [Remote objects to be synchronized with local ones](#synchronization-of-given-remote-objects) | NO | YES |
+
+## Documentation
+
+[API documentation is available at rdoc.info](http://rdoc.info/github/BookingSync/synced/master/frames).

data/lib/synced/model.rb

@@ -18,10 +18,22 @@ module Synced
     #   object's data is stored.
     # @option options [Array] local_attributes: Array of attributes in the remote
     #   object which will be mapped to local object attributes.
+    # @option options [Boolean|Symbol] remove: If it's true all local objects
+    #   within current scope which are not present in the remote array will be
+    #   destroyed.
+    #   If only_updated is enabled, ids of objects to be deleted will be taken
+    #   from the meta part. By default if cancel_at column is present, all
+    #   missing local objects will be canceled with cancel_all,
+    #   if it's missing, all will be destroyed with destroy_all.
+    #   You can also force method to remove local objects by passing it
+    #   to remove: :mark_as_missing.
     def synced(options = {})
+      options.assert_valid_keys(:associations, :data_key, :fields, :id_key,
+        :include, :local_attributes, :mapper, :only_updated, :remove,
+        :synced_all_at_key)
       class_attribute :synced_id_key, :synced_all_at_key, :synced_data_key,
         :synced_local_attributes, :synced_associations, :synced_only_updated,
-        :synced_mapper_module
+        :synced_mapper, :synced_remove, :synced_include, :synced_fields
       self.synced_id_key           = options.fetch(:id_key, :synced_id)
       self.synced_all_at_key       = options.fetch(:synced_all_at_key,
         synced_column_presence(:synced_all_at))
@@ -31,7 +43,10 @@ module Synced
       self.synced_associations     = options.fetch(:associations, [])
       self.synced_only_updated     = options.fetch(:only_updated,
         column_names.include?(synced_all_at_key.to_s))
-      self.synced_mapper_module    = options.fetch(:mapper, nil)
+      self.synced_mapper           = options.fetch(:mapper, nil)
+      self.synced_remove           = options.fetch(:remove, false)
+      self.synced_include          = options.fetch(:include, [])
+      self.synced_fields           = options.fetch(:fields, [])
       include Synced::HasSyncedData
     end
 
@@ -50,7 +65,8 @@ module Synced
     #   missing local objects will be canceled with cancel_all,
     #   if it's missing, all will be destroyed with destroy_all.
     #   You can also force method to remove local objects by passing it
-    #   to remove: :mark_as_missing.
+    #   to remove: :mark_as_missing. This option can be defined in the model
+    #   and then overwritten in the synchronize method.
     # @param api [BookingSync::API::Client] - API client to be used for fetching
     #   remote objects
     # @example Synchronizing amenities
@@ -63,23 +79,24 @@ module Synced
     #
     #  Rental.synchronize(remote: remote_rentals, scope: website)
     #
-    def synchronize(remote: nil, model_class: self, scope: nil, remove: false,
-      include: nil, api: nil)
-      options = {
-        scope: scope,
-        id_key: synced_id_key,
+    def synchronize(options = {})
+      options.assert_valid_keys(:api, :fields, :include, :remote, :remove,
+        :scope)
+      options.symbolize_keys!
+      options[:remove]  = synced_remove unless options.has_key?(:remove)
+      options[:include] = Array(synced_include) unless options.has_key?(:include)
+      options[:fields]  = Array(synced_fields) unless options.has_key?(:fields)
+      options.merge!({
+        id_key:            synced_id_key,
+        synced_data_key:   synced_data_key,
         synced_all_at_key: synced_all_at_key,
-        data_key: synced_data_key,
-        remove: remove,
-        local_attributes: synced_local_attributes,
-        associations: synced_associations,
-        only_updated: synced_only_updated,
-        include: include,
-        api: api,
-        mapper: synced_mapper_module
-      }
-      synchronizer = Synced::Synchronizer.new(remote, model_class, options)
-      synchronizer.perform
+        data_key:          synced_data_key,
+        local_attributes:  synced_local_attributes,
+        associations:      synced_associations,
+        only_updated:      synced_only_updated,
+        mapper:            synced_mapper
+      })
+      Synced::Synchronizer.new(self, options).perform
     end
 
     private

data/lib/synced/synchronizer.rb

@@ -37,7 +37,7 @@ module Synced
     #   remote objects
     # @option options [Module] mapper: Module class which will be used for
     #   mapping remote objects attributes into local object attributes
-    def initialize(remote_objects, model_class, options = {})
+    def initialize(model_class, options = {})
       @model_class       = model_class
       @scope             = options[:scope]
       @id_key            = options[:id_key]
@@ -48,9 +48,12 @@ module Synced
       @include           = options[:include]
       @local_attributes  = options[:local_attributes]
       @api               = options[:api]
-      @mapper            = options[:mapper]
+      @mapper            = options[:mapper].respond_to?(:call) ?
+                             options[:mapper].call : options[:mapper]
+      @fields            = options[:fields]
+      @remove            = options[:remove]
       @associations      = Array(options[:associations])
-      @remote_objects    = Array(remote_objects) if remote_objects
+      @remote_objects    = Array(options[:remote]) if options.has_key?(:remote)
       @request_performed = false
     end
 
@@ -166,6 +169,7 @@ module Synced
           options[:include] ||= []
           options[:include] += @include
         end
+        options[:fields] = @fields if @fields.present?
         options[:updated_since] = minimum_updated_at if updated_since_enabled?
         options[:auto_paginate] = true
       end

data/lib/synced/version.rb

@@ -1,3 +1,3 @@
 module Synced
-  VERSION = "0.0.11"
+  VERSION = "1.0.0.rc1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: synced
 version: !ruby/object:Gem::Version
-  version: 0.0.11
+  version: 1.0.0.rc1
 platform: ruby
 authors:
 - Sebastien Grosjean
@@ -9,132 +9,132 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-08 00:00:00.000000000 Z
+date: 2014-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: 4.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: 4.0.0
 - !ruby/object:Gem::Dependency
   name: bookingsync-api
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: 0.0.20
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: 0.0.20
 - !ruby/object:Gem::Dependency
   name: hashie
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: guard-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: timecop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: Keep your BookingSync Application synced with BookingSync.
@@ -144,16 +144,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- MIT-LICENSE
-- README.md
-- Rakefile
-- config/routes.rb
-- lib/synced.rb
 - lib/synced/has_synced_data.rb
 - lib/synced/model.rb
 - lib/synced/rails.rb
 - lib/synced/synchronizer.rb
 - lib/synced/version.rb
+- lib/synced.rb
+- MIT-LICENSE
+- Rakefile
+- README.md
 homepage: https://github.com/BookingSync/synced
 licenses:
 - MIT
@@ -164,19 +163,18 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
 summary: Keep your BookingSync Application synced with BookingSync.
 test_files: []
-has_rdoc: 

data/config/routes.rb

@@ -1,2 +0,0 @@
-Rails.application.routes.draw do
-end