shrine 3.0.0 → 3.0.1

data/doc/carrierwave.md

@@ -179,15 +179,15 @@ uploaded processed files into the database (including any extracted metadata),
 which then becomes the source of truth on which versions have been generated.
 
 ```rb
-photo.image              #=> #<Shrine::UploadedFile @id="original.jpg" ...>
+photo.image              #=> #<Shrine::UploadedFile id="original.jpg" ...>
 photo.image_derivatives  #=> {}
 
 photo.image_derivatives! # triggers processing
 photo.image_derivatives  #=>
 # {
-#   large: #<Shrine::UploadedFile @id="large.jpg" @metadata={"size"=>873232, ...} ...>,
-#   medium: #<Shrine::UploadedFile @id="medium.jpg" @metadata={"size"=>94823, ...} ...>,
-#   small: #<Shrine::UploadedFile @id="small.jpg" @metadata={"size"=>37322, ...} ...>,
+#   large:  #<Shrine::UploadedFile id="large.jpg"  metadata={"size"=>873232, ...} ...>,
+#   medium: #<Shrine::UploadedFile id="medium.jpg" metadata={"size"=>94823,  ...} ...>,
+#   small:  #<Shrine::UploadedFile id="small.jpg"  metadata={"size"=>37322,  ...} ...>,
 # }
 ```
 

data/doc/design.md

@@ -159,11 +159,11 @@ name (an "image" attachment will be saved to `image_data` field):
 attacher = Shrine::Attacher.from_model(photo, :image)
 
 attacher.assign(file)
-attacher.file #=> #<Shrine::UploadedFile @storage_key=:cache ...>
+attacher.file #=> #<Shrine::UploadedFile storage=:cache ...>
 attacher.record.image_data #=> "{\"storage\":\"cache\",\"id\":\"9260ea09d8effd.jpg\",\"metadata\":{...}}"
 
 attacher.finalize
-attacher.file #=> #<Shrine::UploadedFile @storage_key=:store ...>
+attacher.file #=> #<Shrine::UploadedFile storage=:store ...>
 attacher.record.image_data #=> "{\"storage\":\"store\",\"id\":\"ksdf02lr9sf3la.jpg\",\"metadata\":{...}}"
 ```
 

data/doc/external/articles.md

@@ -17,6 +17,7 @@ title: Articles
 * [Better File Uploads with Shrine: Processing](https://twin.github.io/better-file-uploads-with-shrine-processing/)
 * [Better File Uploads with Shrine: Metadata](https://twin.github.io/better-file-uploads-with-shrine-metadata/)
 * [Better File Uploads with Shrine: Direct Uploads](https://twin.github.io/better-file-uploads-with-shrine-direct-uploads)
+* [Shrine 3.0 Released](https://twin.github.io/shrine-3-0-released/)
 
 ## Other Articles
 

data/doc/external/extensions.md

@@ -36,6 +36,7 @@ title: Extensions
 * [shrine-mongoid](https://github.com/shrinerb/shrine-mongoid)
 * [shrine-rails](https://github.com/abepetrillo/shrine-rails)
 * [shrine-reform](https://github.com/shrinerb/shrine-reform)
+* [shrine-rom](https://github.com/shrinerb/shrine-rom)
 * [shrine-tus](https://github.com/shrinerb/shrine-tus)
 
 ## Libraries

data/doc/getting_started.md

@@ -278,7 +278,7 @@ uploader.upload Shrine::UploadedFile.new(...)               # upload from Shrine
 
 The `Shrine::UploadedFile` object represents the file that was uploaded to a
 storage, and it's what's returned from `Shrine#upload` or when retrieving a
-record [attachment]. It contains the following information:
+record [attachment]. It contains the following data:
 
 | Key        | Description                                        |
 | :-------   | :----------                                        |
@@ -288,11 +288,12 @@ record [attachment]. It contains the following information:
 
 ```rb
 uploaded_file = uploader.upload(file)
-uploaded_file.data #=> {"id"=>"949sdjg834.jpg","storage"=>"store","metadata"=>{...}}
+uploaded_file #=> #<Shrine::UploadedFile id="949sdjg834.jpg" storage=:store metadata={...}>
 
-uploaded_file.id       #=> "949sdjg834.jpg"
-uploaded_file.storage  #=> #<Shrine::Storage::S3>
-uploaded_file.metadata #=> {...}
+uploaded_file.id          # => "949sdjg834.jpg"
+uploaded_file.storage_key # => :store
+uploaded_file.storage     # => #<Shrine::Storage::S3>
+uploaded_file.metadata    # => {...}
 ```
 
 It comes with many convenient methods that delegate to the storage:
@@ -364,13 +365,13 @@ photo.image #=> nil
 
 # the assigned file is cached to temporary storage and written to `image_data` column
 photo.image = File.open("waterfall.jpg")
-photo.image      #=> #<Shrine::UploadedFile @data={...}>
+photo.image      #=> #<Shrine::UploadedFile ...>
 photo.image_url  #=> "/uploads/cache/0sdfllasfi842.jpg"
 photo.image_data #=> '{"id":"0sdfllasfi842.jpg","storage":"cache","metadata":{...}}'
 
 # the cached file is promoted to permanent storage and saved to `image_data` column
 photo.save
-photo.image      #=> #<Shrine::UploadedFile @data={...}>
+photo.image      #=> #<Shrine::UploadedFile ...>
 photo.image_url  #=> "/uploads/store/l02kladf8jlda.jpg"
 photo.image_data #=> '{"id":"l02kladf8jlda.jpg","storage":"store","metadata":{...}}'
 

data/doc/paperclip.md

@@ -141,7 +141,7 @@ Record][activerecord], [Sequel][sequel], [ROM][rom], [Hanami][hanami] and
 ```rb
 attacher = ImageUploader::Attacher.new
 attacher.attach File.open("nature.jpg")
-attacher.file #=> #<Shrine::UploadedFile @id="f4ba5bdbf366ef0b.jpg" ...>
+attacher.file #=> #<Shrine::UploadedFile id="f4ba5bdbf366ef0b.jpg" ...>
 attacher.url  #=> "https://my-bucket.s3.amazonaws.com/f4ba5bdbf366ef0b.jpg"
 attacher.data #=> { "id" => "f4ba5bdbf366ef0b.jpg", "storage" => "store", "metadata" => { ... } }
 ```
@@ -206,15 +206,15 @@ uploaded processed files into the database (including any extracted metadata),
 which then becomes the source of truth on which versions have been generated.
 
 ```rb
-photo.image              #=> #<Shrine::UploadedFile @id="original.jpg" ...>
+photo.image              #=> #<Shrine::UploadedFile id="original.jpg" ...>
 photo.image_derivatives  #=> {}
 
 photo.image_derivatives! # triggers processing
 photo.image_derivatives  #=>
 # {
-#   large: #<Shrine::UploadedFile @id="large.jpg" @metadata={"size"=>873232, ...} ...>,
-#   medium: #<Shrine::UploadedFile @id="medium.jpg" @metadata={"size"=>94823, ...} ...>,
-#   small: #<Shrine::UploadedFile @id="small.jpg" @metadata={"size"=>37322, ...} ...>,
+#   large: #<Shrine::UploadedFile id="large.jpg" metadata={"size"=>873232, ...} ...>,
+#   medium: #<Shrine::UploadedFile id="medium.jpg" metadata={"size"=>94823, ...} ...>,
+#   small: #<Shrine::UploadedFile id="small.jpg" metadata={"size"=>37322, ...} ...>,
 # }
 ```
 

data/doc/plugins/activerecord.md

@@ -28,12 +28,12 @@ photo = Photo.new
 
 photo.image = file # cache attachment
 
-photo.image      #=> #<Shrine::UploadedFile @id="bc2e13.jpg" @storage_key=:cache ...>
+photo.image      #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
 photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
 
 photo.save # persist, promote attachment, then persist again
 
-photo.image      #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+photo.image      #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
 
 photo.destroy # delete attachment
@@ -192,14 +192,14 @@ attacher = ImageUploader::Attacher.from_model(photo, :image)
 
 attacher.assign(file) # cache
 
-attacher.file    #=> #<Shrine::UploadedFile @id="bc2e13.jpg" @storage_key=:cache ...>
+attacher.file    #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
 photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
 
 photo.save        # persist
 attacher.finalize # promote
 photo.save        # persist
 
-attacher.file    #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+attacher.file    #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
 ```
 

data/doc/plugins/derivatives.md

@@ -87,13 +87,13 @@ The `#<name>_derivatives!` model method delegates to
 `Shrine::Attacher` directly:
 
 ```rb
-attacher.file               #=> #<Shrine::UploadedFile @id="original.jpg" @storage_key=:store ...>
+attacher.file               #=> #<Shrine::UploadedFile id="original.jpg" storage=:store ...>
 attacher.create_derivatives # calls registered processor and uploads results
 attacher.derivatives        #=>
 # {
-#   small:  #<Shrine::UploadedFile @id="small.jpg" @storage_key=:store ...>,
-#   medium: #<Shrine::UploadedFile @id="medium.jpg" @storage_key=:store ...>,
-#   large:  #<Shrine::UploadedFile @id="large.jpg" @storage_key=:store ...>,
+#   small:  #<Shrine::UploadedFile id="small.jpg" storage=:store ...>,
+#   medium: #<Shrine::UploadedFile id="medium.jpg" storage=:store ...>,
+#   large:  #<Shrine::UploadedFile id="large.jpg" storage=:store ...>,
 # }
 ```
 

data/doc/plugins/entity.md

@@ -130,16 +130,16 @@ end
 photo    = Photo.new(image_data: '{"id":"...","storage":"...","metadata":{...}}')
 attacher = ImageUploader::Attacher.from_entity(photo, :image)
 
-attacher.file #=> #<Shrine::UploadedFile @id="bc2e13.jpg" @storage_key=:store ...>
+attacher.file #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:store ...>
 
 attacher.attach(file)
-attacher.file          #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+attacher.file          #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 attacher.column_values #=> { image_data: '{"id":"397eca.jpg","storage":"store","metadata":{...}}' }
 
 photo    = Photo.new(attacher.column_values)
 attacher = ImageUploader::Attacher.from_entity(photo, :image)
 
-attacher.file #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+attacher.file #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 ```
 
 ### Loading entity

data/doc/plugins/model.md

@@ -26,12 +26,12 @@ photo = Photo.new
 
 photo.image = file
 
-photo.image      #=> #<Shrine::UploadedFile @id="bc2e13.jpg" @storage_key=:cache ...>
+photo.image      #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
 photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
 
 photo.image_attacher.finalize
 
-photo.image      #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+photo.image      #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
 ```
 
@@ -127,12 +127,12 @@ attacher = ImageUploader::Attacher.from_model(photo, :image)
 
 attacher.assign(file) # cache
 
-attacher.file    #=> #<Shrine::UploadedFile @id="bc2e13.jpg" @storage_key=:cache ...>
+attacher.file    #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
 photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
 
 attacher.finalize # promote
 
-attacher.file    #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+attacher.file    #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
 ```
 

data/doc/plugins/sequel.md

@@ -27,12 +27,12 @@ photo = Photo.new
 
 photo.image = file # cache attachment
 
-photo.image      #=> #<Shrine::UploadedFile @id="bc2e13.jpg" @storage_key=:cache ...>
+photo.image      #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
 photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
 
 photo.save # persist, promote attachment, then persist again
 
-photo.image      #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+photo.image      #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
 
 photo.destroy # delete attachment
@@ -161,14 +161,14 @@ attacher = ImageUploader::Attacher.from_model(photo, :image)
 
 attacher.assign(file) # cache
 
-attacher.file    #=> #<Shrine::UploadedFile @id="bc2e13.jpg" @storage_key=:cache ...>
+attacher.file    #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
 photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
 
 photo.save        # persist
 attacher.finalize # promote
 photo.save        # persist
 
-attacher.file    #=> #<Shrine::UploadedFile @id="397eca.jpg" @storage_key=:store ...>
+attacher.file    #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
 photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
 ```
 

data/doc/plugins/versions.md

@@ -49,10 +49,10 @@ user.avatar_data #=>
 
 user.avatar #=>
 # {
-#   :original => #<Shrine::UploadedFile @data={"id"=>"0gsdf.jpg", ...}>,
-#   :large    => #<Shrine::UploadedFile @data={"id"=>"lg043.jpg", ...}>,
-#   :medium   => #<Shrine::UploadedFile @data={"id"=>"kd9fk.jpg", ...}>,
-#   :small    => #<Shrine::UploadedFile @data={"id"=>"932fl.jpg", ...}>,
+#   :original => #<Shrine::UploadedFile id=0gsdf.jpg" ...}>,
+#   :large    => #<Shrine::UploadedFile id=lg043.jpg" ...}>,
+#   :medium   => #<Shrine::UploadedFile id=kd9fk.jpg" ...}>,
+#   :small    => #<Shrine::UploadedFile id=932fl.jpg" ...}>,
 # }
 
 user.avatar[:medium]     #=> #<Shrine::UploadedFile>

data/doc/release_notes/3.0.0.md

@@ -3,312 +3,326 @@ title: Shrine 3.0.0
 ---
 
 This guide covers all the changes in the 3.0.0 version of Shrine. If you're
-currently using Shrine 2.x, see [Upgrading to Shrine 3.x] for instructions on
-how to upgrade.
+currently using Shrine 2.x, see **[Upgrading to Shrine 3.x]** for instructions
+on how to upgrade.
 
 ## Major features
 
-* The new **[`derivatives`][derivatives]** plugin has been added for storing
-  additional processed files alongside the main file.
+### Derivatives
 
-  ```rb
-  Shrine.plugin :derivatives
-  ```
-  ```rb
-  class ImageUploader < Shrine
-    Attacher.derivatives_processor do |original|
-      magick = ImageProcessing::MiniMagick.source(original) 
-
-      {
-        large:  magick.resize_to_limit!(800, 800),
-        medium: magick.resize_to_limit!(500, 500),
-        small:  magick.resize_to_limit!(300, 300),
-      }
-    end
-  end
-  ```
-  ```rb
-  photo = Photo.new(photo_params)
-  photo.image_derivatives! # creates derivatives
-  photo.save
-  ```
-
-  This is a rewrite of the [`versions`][versions] plugin, bringing numerous
-  improvements:
-
-  - processed files are separated from the main file
-
-    ```rb
-    photo.image_data #=>
-    # {
-    #   "id": "original.jpg",
-    #   "storage": "store",
-    #   "metadata": { ... },
-    #   "derivatives": {
-    #     "large": { "id": "large.jpg", "storage": "store", "metadata": { ... } },
-    #     "medium": { "id": "medium.jpg", "storage": "store", "metadata": { ... } },
-    #     "small": { "id": "small.jpg", "storage": "store", "metadata": { ... } }
-    #   }
-    # }
-
-    photo.image             #=> #<Shrine::UploadedFile @id="original.jpg" ...>
-    photo.image_derivatives #=>
-    # {
-    #   large: #<Shrine::UploadedFile @id="large.jpg" ...>,
-    #   medium: #<Shrine::UploadedFile @id="medium.jpg" ...>,
-    #   small: #<Shrine::UploadedFile @id="small.jpg" ...>,
-    # }
-    ```
-
-  - processing is decoupled from promotion
-
-    ```rb
-    photo = Photo.create(image: file) # promote original file to permanent storage
-    photo.image_derivatives!          # generate derivatives after promotion
-    photo.save                        # save derivatives data
-    ```
-
-  - ability to add or remove processed files at any point
-
-    ```rb
-    class ImageUploader < Shrine
-      Attacher.derivatives_processor :thumbnails do |original|
-        # ...
-      end
-
-      Attacher.derivatives_processor :crop do |original, left:, top:, width:, height:|
-        vips = ImageProcessing::Vips.source(original)
-
-        { cropped: vips.crop!(left, top, width, height) }
-      end
-    end
-    ```
-    ```rb
-    photo.image_derivatives!(:thumbnails)
-    photo.image_derivatives #=> { large: ..., medium: ..., small: ... }
-    photo.save
-
-    # ... sometime later ...
-
-    photo.image_derivatives!(:crop, left: 0, top: 0, width: 300, height: 300)
-    photo.image_derivatives #=> { large: ..., medium: ..., small: ..., cropped: ... }
-    photo.save
-    ```
+The new **[`derivatives`][derivatives]** plugin has been added for storing
+additional processed files alongside the main file.
 
-  - possibility of uploading processed files to different storage
+```rb
+Shrine.plugin :derivatives
+```
+```rb
+class ImageUploader < Shrine
+  Attacher.derivatives_processor do |original|
+    magick = ImageProcessing::MiniMagick.source(original) 
 
-    ```rb
-    class ImageUploader < Shrine
-      # specify storage for all derivatives
-      Attacher.derivatives_storage :other_store
-
-      # or specify storage per derivative
-      Attacher.derivatives_storage { |derivative| :other_store }
-    end
-    ```
-    ```rb
-    photo = Photo.create(image: file)
-    photo.image.storage_key #=> :store
+    {
+      large:  magick.resize_to_limit!(800, 800),
+      medium: magick.resize_to_limit!(500, 500),
+      small:  magick.resize_to_limit!(300, 300),
+    }
+  end
+end
+```
+```rb
+photo = Photo.new(photo_params)
+photo.image_derivatives! # creates derivatives
+photo.save
+```
 
-    photo.image_derivatives!
-    photo.image_derivatives[:large].storage_key #=> :other_store
-    ```
+This is a rewrite of the [`versions`][versions] plugin, bringing numerous
+improvements:
 
-* The [`Shrine::Attacher`][attacher] class has been rewritten and can now be
-  used without models:
+* processed files are separated from the main file
 
   ```rb
-  attacher = Shrine::Attacher.new
-  attacher.attach(file)
-  attacher.file #=> #<Shrine::UploadedFile>
+  photo.image_data #=>
+  # {
+  #   "id": "original.jpg",
+  #   "storage": "store",
+  #   "metadata": { ... },
+  #   "derivatives": {
+  #     "large": { "id": "large.jpg", "storage": "store", "metadata": { ... } },
+  #     "medium": { "id": "medium.jpg", "storage": "store", "metadata": { ... } },
+  #     "small": { "id": "small.jpg", "storage": "store", "metadata": { ... } }
+  #   }
+  # }
+
+  photo.image             #=> #<Shrine::UploadedFile id="original.jpg" ...>
+  photo.image_derivatives #=>
+  # {
+  #   large: #<Shrine::UploadedFile id="large.jpg" ...>,
+  #   medium: #<Shrine::UploadedFile id="medium.jpg" ...>,
+  #   small: #<Shrine::UploadedFile id="small.jpg" ...>,
+  # }
   ```
 
-  The `Attacher#data`, `Attacher#load_data`, and `Attacher.from_data` methods
-  have been added for dumping and loading the attached file:
+* processing is decoupled from promotion
 
   ```rb
-  # dump attached file into a serializable Hash
-  data = attacher.data #=> { "id" => "abc123.jpg", "storage" => "store", "metadata" => { ... } }
-  ```
-  ```rb
-  # initialize attacher from attached file data...
-  attacher = Shrine::Attacher.from_data(data)
-  attacher.file #=> #<Shrine::UploadedFile @id="abc123.jpg" @storage_key=:store @metadata={...}>
-
-  # ...or load attached file into an existing attacher
-  attacher = Shrine::Attacher.new
-  attacher.load_data(data)
-  attacher.file #=> #<Shrine::UploadedFile>
+  photo = Photo.create(image: file) # promote original file to permanent storage
+  photo.image_derivatives!          # generate derivatives after promotion
+  photo.save                        # save derivatives data
   ```
 
-  Several more methods have been added:
+- ability to add or remove processed files at any point
 
-  - `Attacher#attach` – attaches the file directly to permanent storage
-  - `Attacher#attach_cached` – extracted from `Attacher#assign`
-  - `Attacher#upload` – calls `Shrine#upload`, passing `:record` and `:name` context
-  - `Attacher#file` – alias for `Attacher#get`
-  - `Attacher#cache_key` – returns temporary storage key (`:cache` by default)
-  - `Attacher#store_key` – returns permanent storage key (`:store` by default)
-
-* The new [`column`][column] plugin adds the ability to serialize attached file
-  data, in format suitable for writing into a database column.
-
-  ```rb
-  Shrine.plugin :column
-  ```
   ```rb
-  # dump attached file data into a JSON string
-  data = attacher.column_data #=> '{"id":"abc123.jpg","storage":"store","metadata":{...}}'
-  ```
-  ```rb
-  # initialize attacher from attached file data...
-  attacher = Shrine::Attacher.from_column(data)
-  attacher.file #=> #<Shrine::UploadedFile @id="abc123.jpg" @storage_key=:store @metadata={...}>
-
-  # ...or load attached file into an existing attacher
-  attacher = Shrine::Attacher.new
-  attacher.load_column(data)
-  attacher.file #=> #<Shrine::UploadedFile>
-  ```
+  class ImageUploader < Shrine
+    Attacher.derivatives_processor :thumbnails do |original|
+      # ...
+    end
 
-* The new [`entity`][entity] plugin adds support for immutable structs, which
-  are commonly used with ROM, Hanami and dry-rb.
+    Attacher.derivatives_processor :crop do |original, left:, top:, width:, height:|
+      vips = ImageProcessing::Vips.source(original)
 
-  ```rb
-  Shrine.plugin :entity
-  ```
-  ```rb
-  class Photo < Hanami::Entity
-    include Shrine::Attachment(:image)
+      { cropped: vips.crop!(left, top, width, height) }
+    end
   end
   ```
   ```rb
-  photo = Photo.new(image_data: '{"id":"abc123.jpg","storage":"store","metadata":{...}}')
-  photo.image #=> #<Shrine::UploadedFile @id="abc123.jpg" @storage_key=:store ...>
-  ```
+  photo.image_derivatives!(:thumbnails)
+  photo.image_derivatives #=> { large: ..., medium: ..., small: ... }
+  photo.save
 
-* The new [`model`][model] plugin adds support for mutable structs, which is
-  used by `activerecord` and `sequel` plugins.
+  # ... sometime later ...
 
-  ```rb
-  Shrine.plugin :model
-  ```
-  ```rb
-  class Photo < Struct.new(:image_data)
-    include Shrine::Attachment(:image)
-  end
-  ```
-  ```rb
-  photo = Photo.new
-  photo.image = file
-  photo.image #=> #<Shrine::UploadedFile @id="abc123.jpg" @storage_key=:cache ...>
-  photo.image_data #=> #=> '{"id":"abc123.jpg", "storage":"cache", "metadata":{...}}'
+  photo.image_derivatives!(:crop, left: 0, top: 0, width: 300, height: 300)
+  photo.image_derivatives #=> { large: ..., medium: ..., small: ..., cropped: ... }
+  photo.save
   ```
 
-* The [`backgrounding`][backgrounding] plugin has been rewritten for more
-  flexibility and simplicity. The new usage is much more explicit:
+* possibility of uploading processed files to different storage
 
   ```rb
-  Shrine.plugin :backgrounding
-  Shrine::Attacher.promote_block do
-    PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
-  end
-  Shrine::Attacher.destroy_block do
-    DestroyJob.perform_async(self.class.name, data)
-  end
-  ```
-  ```rb
-  class PromoteJob
-    include Sidekiq::Worker
-
-    def perform(attacher_class, record_class, record.id, name, file_data)
-      attacher_class = Object.const_get(attacher_class)
-      record         = Object.const_get(record_class).find(record_id) # if using Active Record
+  class ImageUploader < Shrine
+    # specify storage for all derivatives
+    Attacher.derivatives_storage :other_store
 
-      attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
-      attacher.atomic_promote
-    rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
-      # attachment has changed or the record has been deleted, nothing to do
-    end
+    # or specify storage per derivative
+    Attacher.derivatives_storage { |derivative| :other_store }
   end
   ```
   ```rb
-  class DestroyJob
-    include Sidekiq::Worker
-
-    def perform(attacher_class, data)
-      attacher_class = Object.const_get(attacher_class)
+  photo = Photo.create(image: file)
+  photo.image.storage_key #=> :store
+
+  photo.image_derivatives!
+  photo.image_derivatives[:large].storage_key #=> :other_store
+  ```
+
+### Attacher redesign
+
+The [`Shrine::Attacher`][attacher] class has been rewritten and can now be
+used without models:
+
+```rb
+attacher = Shrine::Attacher.new
+attacher.attach(file)
+attacher.file #=> #<Shrine::UploadedFile>
+```
+
+The `Attacher#data`, `Attacher#load_data`, and `Attacher.from_data` methods
+have been added for dumping and loading the attached file:
+
+```rb
+# dump attached file into a serializable Hash
+data = attacher.data #=> { "id" => "abc123.jpg", "storage" => "store", "metadata" => { ... } }
+```
+```rb
+# initialize attacher from attached file data...
+attacher = Shrine::Attacher.from_data(data)
+attacher.file #=> #<Shrine::UploadedFile id="abc123.jpg" storage=:store metadata={...}>
+
+# ...or load attached file into an existing attacher
+attacher = Shrine::Attacher.new
+attacher.load_data(data)
+attacher.file #=> #<Shrine::UploadedFile>
+```
+
+Several more methods have been added:
+
+- `Attacher#attach` – attaches the file directly to permanent storage
+- `Attacher#attach_cached` – extracted from `Attacher#assign`
+- `Attacher#upload` – calls `Shrine#upload`, passing `:record` and `:name` context
+- `Attacher#file` – alias for `Attacher#get`
+- `Attacher#cache_key` – returns temporary storage key (`:cache` by default)
+- `Attacher#store_key` – returns permanent storage key (`:store` by default)
+
+#### Column
+
+The new [`column`][column] plugin adds the ability to serialize attached file
+data, in format suitable for writing into a database column.
+
+```rb
+Shrine.plugin :column
+```
+```rb
+# dump attached file data into a JSON string
+data = attacher.column_data #=> '{"id":"abc123.jpg","storage":"store","metadata":{...}}'
+```
+```rb
+# initialize attacher from attached file data...
+attacher = Shrine::Attacher.from_column(data)
+attacher.file #=> #<Shrine::UploadedFile id="abc123.jpg" storage=:store metadata={...}>
+
+# ...or load attached file into an existing attacher
+attacher = Shrine::Attacher.new
+attacher.load_column(data)
+attacher.file #=> #<Shrine::UploadedFile>
+```
+
+#### Entity
+
+The new [`entity`][entity] plugin adds support for immutable structs, which
+are commonly used with ROM, Hanami and dry-rb.
+
+```rb
+Shrine.plugin :entity
+```
+```rb
+class Photo < Hanami::Entity
+  include Shrine::Attachment(:image)
+end
+```
+```rb
+photo = Photo.new(image_data: '{"id":"abc123.jpg","storage":"store","metadata":{...}}')
+photo.image #=> #<Shrine::UploadedFile id="abc123.jpg" storage=:store ...>
+```
+
+#### Model
+
+The new [`model`][model] plugin adds support for mutable structs, which is
+used by `activerecord` and `sequel` plugins.
+
+```rb
+Shrine.plugin :model
+```
+```rb
+class Photo < Struct.new(:image_data)
+  include Shrine::Attachment(:image)
+end
+```
+```rb
+photo = Photo.new
+photo.image = file
+photo.image #=> #<Shrine::UploadedFile id="abc123.jpg" storage=:cache ...>
+photo.image_data #=> #=> '{"id":"abc123.jpg", "storage":"cache", "metadata":{...}}'
+```
+
+### Backgrounding rewrite
 
-      attacher = attacher_class.from_data(data)
-      attacher.destroy
-    end
+* The [`backgrounding`][backgrounding] plugin has been rewritten for more
+flexibility and simplicity. The new usage is much more explicit:
+
+```rb
+Shrine.plugin :backgrounding
+Shrine::Attacher.promote_block do
+  PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
+end
+Shrine::Attacher.destroy_block do
+  DestroyJob.perform_async(self.class.name, data)
+end
+```
+```rb
+class PromoteJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record.id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
+    attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
+    attacher.atomic_promote
+  rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
+    # attachment has changed or the record has been deleted, nothing to do
   end
-  ```
+end
+```
+```rb
+class DestroyJob
+  include Sidekiq::Worker
 
-  There are several main differences compared to the old implementation:
-
-  - we are in charge of passing the record to the background job
-  - we can access the attacher before promotion
-  - we can react to errors that caused promotion to abort
-
-  We can now also register backgrounding hooks on an attacher instance, allowing
-  us to pass additional parameters to the background job:
-
-  ```rb
-  photo = Photo.new(photo_params)
+  def perform(attacher_class, data)
+    attacher_class = Object.const_get(attacher_class)
 
-  photo.image_attacher.promote_block do |attacher|
-    PromoteJob.perform_async(
-      attacher.class.name,
-      attacher.record.class.name,
-      attacher.record.id,
-      attacher.name,
-      attacher.file_data,
-      current_user.id, # <== parameters from the controller
-    )
+    attacher = attacher_class.from_data(data)
+    attacher.destroy
   end
+end
+```
 
-  photo.save # will call our instance-level backgrounding hook
-  ```
+There are several main differences compared to the old implementation:
 
-* The persistence plugins (`activerecord`, `sequel`) now implement a unified
-  [persistence] interface:
+- we are in charge of passing the record to the background job
+- we can access the attacher before promotion
+- we can react to errors that caused promotion to abort
 
-  | Method                    | Description                                           |
-  | :-----------------        | :----------                                           |
-  | `Attacher#persist`        | persists attachment data                              |
-  | `Attacher#atomic_persist` | persists attachment data if attachment hasn’t changed |
-  | `Attacher#atomic_promote` | promotes cached file and atomically persists changes  |
+We can now also register backgrounding hooks on an attacher instance, allowing
+us to pass additional parameters to the background job:
 
-  The "atomic" methods use the new [`atomic_helpers`][atomic_helpers] plugin,
-  and are useful for background jobs. For example, this is how we'd use them to
-  implement metadata extraction in the background in a concurrency-safe way:
+```rb
+photo = Photo.new(photo_params)
 
-  ```rb
-  MetadataJob.perform_async(
+photo.image_attacher.promote_block do |attacher|
+  PromoteJob.perform_async(
     attacher.class.name,
     attacher.record.class.name,
     attacher.record.id,
     attacher.name,
     attacher.file_data,
+    current_user.id, # <== parameters from the controller
   )
-  ```
-  ```rb
-  class MetadataJob
-    include Sidekiq::Worker
-
-    def perform(attacher_class, record_class, record_id, name, file_data)
-      attacher_class = Object.const_get(attacher_class)
-      record         = Object.const_get(record_class).find(record_id) # if using Active Record
-
-      attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
-      attacher.refresh_metadata! # extract metadata
-      attacher.atomic_persist    # persist if attachment hasn't changed
-    rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
-      # attachment has changed or record has been deleted, nothing to do
-    end
+end
+
+photo.save # will call our instance-level backgrounding hook
+```
+
+### Persistence interface
+
+The persistence plugins (`activerecord`, `sequel`) now implement a unified
+[persistence] interface:
+
+| Method                    | Description                                           |
+| :-----------------        | :----------                                           |
+| `Attacher#persist`        | persists attachment data                              |
+| `Attacher#atomic_persist` | persists attachment data if attachment hasn’t changed |
+| `Attacher#atomic_promote` | promotes cached file and atomically persists changes  |
+
+The "atomic" methods use the new [`atomic_helpers`][atomic_helpers] plugin,
+and are useful for background jobs. For example, this is how we'd use them to
+implement metadata extraction in the background in a concurrency-safe way:
+
+```rb
+MetadataJob.perform_async(
+  attacher.class.name,
+  attacher.record.class.name,
+  attacher.record.id,
+  attacher.name,
+  attacher.file_data,
+)
+```
+```rb
+class MetadataJob
+  include Sidekiq::Worker
+
+  def perform(attacher_class, record_class, record_id, name, file_data)
+    attacher_class = Object.const_get(attacher_class)
+    record         = Object.const_get(record_class).find(record_id) # if using Active Record
+
+    attacher = attacher_class.retrieve(model: record, name: name, file: file_data)
+    attacher.refresh_metadata! # extract metadata
+    attacher.atomic_persist    # persist if attachment hasn't changed
+  rescue Shrine::AttachmentChanged, ActiveRecord::RecordNotFound
+    # attachment has changed or record has been deleted, nothing to do
   end
-  ```
+end
+```
 
 ## Other new plugins
 
@@ -353,7 +367,7 @@ how to upgrade.
   ```rb
   attacher = photo.image_attacher
   attacher.form_assign("image" => file, "title" => "...", "description" => "...")
-  attacher.file #=> #<Shrine::UploadedFile @id="..." @storage_key=:cache ...>
+  attacher.file #=> #<Shrine::UploadedFile id="..." storage=:cache ...>
   ```
 
 ## Other features
@@ -686,6 +700,9 @@ how to upgrade.
 * The `Attacher#replace` method has been renamed to
   `Attacher#destroy_previous`.
 
+* The `Attacher#assign` method now raises an exception when non-cached uploaded
+  file is assigned.
+
 * The `Attacher#attached?` method now returns whether a file is attached,
   regardless of whether it was changed or not.