publishing.md in table_sync-6.0

- old
+ new
@@ -1,133 +1,63 @@
-# Publishing changes
+# Publishing
 
-Include `TableSync.sync(self)` into a Sequel or ActiveRecord model. `:if` and `:unless` are supported for Sequel and ActiveRecord
+TableSync can be used to send data using RabbitMQ.
 
-Functioning `Rails.cache` is required
+You can do in two ways. Automatic and manual.
+Each one has its own pros and cons.
 
-Example:
+Automatic is used to publish changes in realtime, as soon as the tracked entity changes.
+Usually syncs one entity at a time.
 
-```ruby
-class SomeModel < Sequel::Model
-  TableSync.sync(self, { if: -> (*) { some_code } })
-end
-```
+Manual allows to sync a lot of entities per message.
+But demands greater amount of work and data preparation.
 
-#### #attributes_for_sync
+## Automatic
 
-Models can implement `#attributes_for_sync` to override which attributes are published. If not present, all attributes are published
+Include `TableSync.sync(self)` into a Sequel or ActiveRecord model. 
 
-#### #attrs_for_routing_key
+Options:
 
-Models can implement `#attrs_for_routing_key` to override which attributes are given to `routing_key_callable`. If not present, published attributes are given
+- `if:` and `unless:` - Runs given proc in the scope of an instance. Skips sync on `false` for `if:` and on `true` for `unless:`.
+- `on:` - specify events (`create`, `update`, `destroy`) to trigger sync on. Triggered for all of them without this option.
+- `debounce_time` - min time period allowed between synchronizations.
 
-#### #attrs_for_metadata
+Functioning `Rails.cache` is required.
 
-Models can implement `#attrs_for_metadata` to override which attributes are given to `metadata_callable`. If not present, published attributes are given
+How it works:
 
-#### .table_sync_model_name
+- `TableSync.sync(self)` - registers new callbacks (for `create`, `update`, `destroy`) for ActiveRecord model, and defines `after_create`, `after_update` and `after_destroy` callback methods for Sequel model.
 
-Models can implement `.table_sync_model_name` class method to override the model name used for publishing events. Default is model class name
+- Callbacks call `TableSync::Publishing::Single#publish_later` with given options and object attributes. It enqueues a job which then publishes a message.
 
-#### .table_sync_destroy_attributes(original_attributes)
-
-Models can implement `.table_sync_destroy_attributes` class method to override the attributes used for publishing destroy events. Default is object's original attributes
-
-## Configuration
-
-- `TableSync.publishing_job_class_callable` is a callable which should resolve to a ActiveJob subclass that calls TableSync back to actually publish changes (required)
-
 Example:
 
 ```ruby
-class TableSync::Job < ActiveJob::Base
-  def perform(*args)
-    TableSync::Publishing::Publisher.new(*args).publish_now
-  end
+class SomeModel < Sequel::Model
+  TableSync.sync(self, { if: -> (*) { some_code }, unless: -> (*) { some_code }, on: [:create, :update] })
 end
-```
 
-- `TableSync.batch_publishing_job_class_callable` is a callable which should resolve to a ActiveJob subclass that calls TableSync batch publisher back to actually publish changes (required for batch publisher)
-
-- `TableSync.routing_key_callable` is a callable which resolves which routing key to use when publishing changes. It receives object class and published attributes (required)
-
-Example:
-
-```ruby
-TableSync.routing_key_callable = -> (klass, attributes) { klass.gsub('::', '_').tableize }
+class SomeOtherModel < Sequel::Model
+  TableSync.sync(self)
+end
 ```
 
-- `TableSync.routing_metadata_callable` is a callable that adds RabbitMQ headers which can be used in routing (optional). It receives object class and published attributes. One possible way of using it is defining a headers exchange and routing rules based on key-value pairs (which correspond to sent headers)
+## Manual
 
-Example:
+Directly call one of the publishers. It's the best if you need to sync a lot of data.
+This way you don't even need for the changes to occur.
 
-```ruby
-TableSync.routing_metadata_callable = -> (klass, attributes) { attributes.slice("project_id") }
-```
-
-- `TableSync.exchange_name` defines the exchange name used for publishing (optional, falls back to default Rabbit gem configuration).
-
-- `TableSync.notifier` is a module that provides publish and recieve notifications.
-
-# Manual publishing
-
-`TableSync::Publishing::Publisher.new(object_class, original_attributes, confirm: true, state: :updated, debounce_time: 45)`
-where state is one of `:created / :updated / :destroyed` and `confirm` is Rabbit's confirm delivery flag and optional param `debounce_time` determines debounce time in seconds, 1 minute by default.
-
-# Manual publishing with batches
-
-You can use `TableSync::Publishing::BatchPublisher` to publish changes in batches (array of hashes in `attributes`).
-
-When using `TableSync::Publishing::BatchPublisher`,` TableSync.routing_key_callable` is called as follows: `TableSync.routing_key_callable.call(klass, {})`, i.e. empty hash is passed instead of attributes. And `TableSync.routing_metadata_callable` is not called at all: metadata is set to empty hash.
-
-`TableSync::Publishing::BatchPublisher.new(object_class, original_attributes_array, **options)`, where `original_attributes_array` is an array with hash of attributes of published objects and `options` is a hash of options.
-
-`options` consists of:
-- `confirm`, which is a flag for RabbitMQ, `true` by default
-- `routing_key`, which is a custom key used (if given) to override one from `TableSync.routing_key_callable`, `nil` by default
-- `push_original_attributes` (default value is `false`), if this option is set to `true`,
-original_attributes_array will be pushed to Rabbit instead of fetching records from database and sending their mapped attributes.
-- `headers`, which is an option for custom headers (can be used for headers exchanges routes), `nil` by default
-- `event`, which is an option for event specification (`:destroy` or `:update`), `:update` by default
-
 Example:
 
 ```ruby
-TableSync::Publishing::BatchPublisher.new(
-  "SomeClass",
-  [{ id: 1 }, { id: 2 }],
-  confirm: false,
-  routing_key: "custom_routing_key",
-  push_original_attributes: true,
-  headers: { key: :value },
-  event: :destroy,
-)
+  TableSync::Publishing::Batch.new(
+    object_class: "User",
+    original_attributes: [{ id: 1 }, { id: 2 }],
+    event: :update,
+  ).publish_now
 ```
 
-# Manual publishing with batches (Russian)
+## Read More
 
-С помощью класса `TableSync::Publishing::BatchPublisher` вы можете опубликовать изменения батчами (массивом в `attributes`).
-
-При использовании `TableSync::Publishing::BatchPublisher`, `TableSync.routing_key_callable` вызывается следующим образом: `TableSync.routing_key_callable.call(klass, {})`, то есть вместо аттрибутов передается пустой хэш. А `TableSync.routing_metadata_callable` не вызывается вовсе: в метадате устанавливается пустой хэш.
-
-`TableSync::Publishing::BatchPublisher.new(object_class, original_attributes_array, **options)`, где `original_attributes_array` - массив с аттрибутами публикуемых объектов и `options`- это хэш с дополнительными опциями.
-
-`options` состоит из:
-- `confirm`, флаг для RabbitMQ, по умолчанию - `true`
-- `routing_key`, ключ, который (если указан) замещает ключ, получаемый из `TableSync.routing_key_callable`, по умолчанию - `nil`
-- `push_original_attributes` (значение по умолчанию `false`), если для этой опции задано значение true, в Rabbit будут отправлены original_attributes_array, вместо получения значений записей из базы непосредственно перед отправкой.
-- `headers`, опция для задания headers (можно использовать для задания маршрутов в headers exchange'ах), `nil` по умолчанию
-- `event`, опция для указания типа события (`:destroy` или `:update`), `:update` по умолчанию
-
-Example:
-
-```ruby
-TableSync::Publishing::BatchPublisher.new(
-  "SomeClass",
-  [{ id: 1 }, { id: 2 }],
-  confirm: false,
-  routing_key: "custom_routing_key",
-  push_original_attributes: true,
-  headers: { key: :value },
-  event: :destroy,
-)
-```
+- [Publishers](publishing/publishers.md)
+- [Configuration](publishing/configuration.md)
+- [Manual Sync (examples)](publishing/manual.md)
\ No newline at end of file