transmutation 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f291b37c957ebb47d6d08fc4591d62b93f3cc03cd5bd6ca10dccaa2ad53e140e
-  data.tar.gz: a8df9a22118a10a20112555378756866bbe190ac6f643f7f24089f8327a3bfb2
+  metadata.gz: 93679644e2df5418371d258fb0ede26d51bc9e29c4f835990ce5fa52f38dface
+  data.tar.gz: 64c956a59e385145d1870e949eadbe078db170e950ef711f1c4e46e735a8462c
 SHA512:
-  metadata.gz: 50b1f81caaec7a83824e872d206843ebccd8e2bb143deedb64ffe7d512c2a0c8f8a22731be42f76ee5b10b4ceb249113005ca1246b90a75b0e136af24c2fc090
-  data.tar.gz: 5f66985fbddc2ac6251ee38595dc8c0345e1d8b11d9c36813dc93f86123b10529e045509dffd570bbc44eeb6903e5813f3f1e1f325a6581d61d04c8ed4291f3a
+  metadata.gz: 704c1832843d5d5d19a8ec26c672ed9d5f7cae9716f789f6622d0f3bf38aefb97d7ca9a7290ef954e7dc47824f1173e4c823b52272f4f3363b53e14c61f212c1
+  data.tar.gz: 3eaaf2c39d9c3e6f3ac448ce529932751b23edd43675e4eb04623e985e69ef53f20d95e5862d0e97d543919f690d3f8eff96ccc90d83e7ff43002c0ffe24c0ae

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    transmutation (0.2.1)
+    transmutation (0.2.3)
       zeitwerk (~> 2.6.15)
 
 GEM

data/README.md

@@ -2,19 +2,29 @@
 
 Transmutation is a Ruby gem that provides a simple way to serialize Ruby objects into JSON.
 
-It takes inspiration from the [Active Model Serializers](https://github.com/rails-api/active_model_serializers) gem, but strips away adapters.
+It also adds an opinionated way to automatically find and use serializer classes based on the object's class name and the caller's namespace - it takes inspiration from the [Active Model Serializers](https://github.com/rails-api/active_model_serializers) gem, but strips away adapters.
 
 It aims to be a performant and elegant solution for serializing Ruby objects into JSON, with a touch of opinionated "magic" :sparkles:.
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Install the gem and add to your application's Gemfile by executing:
 
-    $ bundle add transmutation
+```bash
+bundle add transmutation
+```
+
+or manually add the following to your Gemfile:
+
+```ruby
+gem "transmutation"
+```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install transmutation
+```bash
+gem install transmutation
+```
 
 ## Usage
 
@@ -48,13 +58,16 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
   As long as your object responds to the attributes defined in the serializer, it can be serialized.
 
-  - Struct
+  <details>
+    <summary>Struct</summary>
 
     ```ruby
     User = Struct.new(:id, :name, :email)
     ```
+  </details>
 
-  - Class
+  <details>
+    <summary>Class</summary>
 
     ```ruby
     class User
@@ -67,8 +80,10 @@ If bundler is not being used to manage dependencies, install the gem by executin
       end
     end
     ```
+  </details>
 
-  - ActiveRecord
+  <details>
+    <summary>ActiveRecord</summary>
 
     ```ruby
     # == Schema Information
@@ -81,15 +96,142 @@ If bundler is not being used to manage dependencies, install the gem by executin
     class User < ApplicationRecord
     end
     ```
+  </details>
+
+### The `#serialize` method
+
+When you include the `Transmutation::Serialization` module in your class, you can use the `#serialize` method to serialize an object.
+
+It will attempt to find a serializer class based on the object's class name along with the caller's namespace.
+
+```ruby
+include Transmutation::Serialization
+
+serialize(User.new) # => UserSerializer.new(User.new)
+```
+
+If no serializer class is found, it will return the object as is.
+
+### With Ruby on Rails
+
+When then `Transmutation::Serialization` module is included in a Rails controller, it also extends your `render` calls.
+
+```ruby
+class Api::V1::UsersController < ApplicationController
+  include Transmutation::Serialization
+
+  def show
+    user = User.find(params[:id])
 
-### Using the `Transmutation::Serialization` module
+    render json: user
+  end
+end
+```
+
+This will attempt to bubble up the controller namespaces to find a defined serializer class:
+
+- `Api::V1::UserSerializer`
+- `Api::UserSerializer`
+- `UserSerializer`
+
+This calls the `#serialize` method under the hood.
+
+If no serializer class is found, it will fall back to the default behavior of rendering the object as JSON.
+
+You can disable this behaviour by passing `serialize: false` to the `render` method.
+
+```ruby
+render json: user, serialize: false # => user.to_json
+```
+
+## Configuration
+
+You can override the serialization lookup by passing the following options:
+
+- `namespace`: The namespace to use when looking up the serializer class.
+
+  ```ruby
+  render json: user, namespace: "V1" # => Api::V1::V1::UserSerializer
+  ```
+
+  To prevent caller namespaces from being appended to the provided namespace, prefix the namespace with `::`.
+
+  ```ruby
+  render json: user, namespace: "::V1" # => V1::UserSerializer
+  ```
+
+  The `namespace` key is forwarded to the `#serialize` method.
+
+  ```ruby
+  render json: user, namespace: "V1" # => serialize(user, namespace: "V1")
+  ```
+
+- `serializer`: The serializer class to use.
+
+  ```ruby
+  render json: user, serializer: "SuperUserSerializer" # => Api::V1::SuperUserSerializer
+  ```
+
+  To prevent all namespaces from being appended to the serializer class, prefix the serializer class with `::`.
+
+  ```ruby
+  render json: user, serializer: "::SuperUserSerializer" # => SuperUserSerializer
+  ```
+
+  The `serializer` key is forwarded to the `#serialize` method.
+
+  ```ruby
+  render json: user, serializer: "SuperUserSerializer" # => serialize(user, serializer: "SuperUserSerializer")
+  ```
+
+## Opinionated Architecture
+
+If you follow the pattern outlined below, you can take full advantage of the automatic serializer lookup.
+
+### File Structure
+
+```
+.
+└── app/
+    ├── controllers/
+    │   └── api/
+    │       ├── v1/
+    │       │   └── users_controller.rb
+    │       └── v2
+    │           └── users_controller.rb
+    ├── models/
+    │   └── user.rb
+    └── serializers/
+        └── api/
+            ├── v1/
+            │   └── user_serializer.rb
+            ├── v2/
+            │   └── user_serializer.rb
+            └── user_serializer.rb
+```
+
+### Serializers
+
+```ruby
+class Api::UserSerializer < Transmutation::Serializer
+  attributes :id, :name, :email
+end
+
+class Api::V1::UserSerializer < Api::UserSerializer
+  attributes :phone # Added in V1
+end
+
+class Api::V2::UserSerializer < Api::UserSerializer
+  attributes :avatar # Added in V2
+end
+```
+
+To remove attributes, it is recommended to redefine all attributes and start anew. This acts as a reset and makes serializer inheritance much easier to follow.
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/spellbook-technology/transmutation. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/spellbook-technology/transmutation/blob/main/CODE_OF_CONDUCT.md).

data/lib/transmutation/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Transmutation
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 end

data/transmutation.gemspec

@@ -16,6 +16,7 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/spellbook-technology/transmutation"
   spec.metadata["changelog_uri"] = "https://github.com/spellbook-technology/transmutation/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/transmutation"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: transmutation
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - nitemaeric
@@ -62,6 +62,7 @@ metadata:
   homepage_uri: https://github.com/spellbook-technology/transmutation
   source_code_uri: https://github.com/spellbook-technology/transmutation
   changelog_uri: https://github.com/spellbook-technology/transmutation/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/transmutation
 post_install_message: 
 rdoc_options: []
 require_paths: