Introduce serializers to ActiveJob

1 files changed, 63 insertions, 2 deletions

diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md
index 914ef2c327..a7067cb97d 100644
--- a/guides/source/active_job_basics.md
+++ b/guides/source/active_job_basics.md
@@ -339,8 +339,21 @@ UserMailer.welcome(@user).deliver_later # Email will be localized to Esperanto.
 ```
 
 
-GlobalID
---------
+Supported types for arguments
+----------------------------
+
+ActiveJob supports the following types of arguments by default:
+
+  - Basic types (`NilClass`, `String`, `Integer`, `Fixnum`, `Bignum`, `Float`, `BigDecimal`, `TrueClass`, `FalseClass`)
+  - `Symbol` (`:foo`, `:bar`, ...)
+  - `ActiveSupport::Duration` (`1.day`, `2.weeks`, ...)
+  - Classes constants (`ActiveRecord::Base`, `MySpecialService`, ...)
+  - Struct instances (`Struct.new('Rectangle', :width, :height).new(12, 20)`, ...)
+  - `Hash`. Keys should be of `String` or `Symbol` type
+  - `ActiveSupport::HashWithIndifferentAccess`
+  - `Array`
+
+### GlobalID
 
 Active Job supports GlobalID for parameters. This makes it possible to pass live
 Active Record objects to your job instead of class/id pairs, which you then have
@@ -368,6 +381,54 @@ end
 This works with any class that mixes in `GlobalID::Identification`, which
 by default has been mixed into Active Record classes.
 
+### Serializers
+
+You can extend list of supported types for arguments. You just need to define your own serializer.
+
+```ruby
+class MySpecialSerializer
+  class << self
+    # Check if this object should be serialized using this serializer
+    def serialize?(argument)
+      argument.is_a? MySpecialValueObject
+    end
+
+    # Convert an object to a simpler representative using supported object types.
+    # The recommended representative is a Hash with a specific key. Keys can be of basic types only
+    def serialize(object)
+      {
+        key => ActiveJob::Serializers.serialize(object.value)
+        'another_attribute' => ActiveJob::Serializers.serialize(object.another_attribute)
+      }
+    end
+
+    # Check if this serialized value be deserialized using this serializer
+    def deserialize?(argument)
+      argument.is_a?(Hash) && argument.keys == [key, 'another_attribute']
+    end
+
+    # Convert serialized value into a proper object
+    def deserialize(object)
+      value = ActiveJob::Serializers.deserialize(object[key])
+      another_attribute = ActiveJob::Serializers.deserialize(object['another_attribute'])
+      MySpecialValueObject.new value, another_attribute
+    end
+
+    # Define this method if you are using a hash as a representative.
+    # This key will be added to a list of restricted keys for hashes. Use basic types only
+    def key
+      "_aj_custom_dummy_value_object"
+    end
+  end
+end
+```
+
+And now you just need to add this serializer to a list:
+
+```ruby
+ActiveJob::Base.add_serializers(MySpecialSerializer)
+```
+
 
 Exceptions
 ----------