ar2dto 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95a346915889755102f7d55c39719a0b9448072537b4b5f5eb0fa2236be8e94b
-  data.tar.gz: 80a22c29ae6e5cc0544ff5b8bfc8592e22aead54188168fffd59edd7cc851424
+  metadata.gz: c868cca39990a602ad330973d246059d32672f0c7db8bf1ef20a211b666bb851
+  data.tar.gz: 4cf8f1a39fbfb81655ab8b848502694102f1b72a14f5c5201d47cf6cad55c081
 SHA512:
-  metadata.gz: 5fb6538cecb77a3b787249405692c9664d177e276a2ba51f942afd2546a0bdd1137731e58cb220bd094265e991e7d1d73061e63c9996125c56b7ecd2d6b5527d
-  data.tar.gz: 73be4eecaedcc6ab2a2904284f0251eb4e7259d590336eb0cf8ae6214617aba52fb5ed1465b5026b4212f2a6b9450ba5ca3c7e7cbcdb3071357c48e267d638d0
+  metadata.gz: 6090a77b929d7e07c5c03c256b4a29c138d977e0f97b225a76434db04daa18be4735713a39dae663d3130097ff3c6b496e7673747be3cb02062e072bc949d2a5
+  data.tar.gz: 48be3084e1c4840b6bda5dccb572b021f0593bf83f62a70f6b48618784c127891fa66d91749ea6ff9967dda1b8197d48545447c807a61a70028ccfdbb06113db

data/README.md

@@ -1,6 +1,6 @@
 # AR2DTO ![AR2DTO](docs/images/logo.png)
 
-AR2DTO (ActiveRecord to DTO, pronounced R2-D2 or Artoo-Detoo) is a gem that lets you create DTOs (data transfer objects) from your ActiveRecord models. It is a simple and small gem with the goal of encouraging the usage of simpler objects across an app rather than ActiveRecord models, to help with coupling issues in large Rails apps.
+AR2DTO (ActiveRecord to DTO, pronounced R2-D2 or Artoo-Detoo) is a gem that lets you create [DTOs](https://martinfowler.com/eaaCatalog/dataTransferObject.html) (data transfer objects) from your ActiveRecord models. It is a simple and small gem to encourage the usage of simpler objects across an app rather than ActiveRecord models, to help with coupling issues in large Rails apps.
 
 ![CI](https://github.com/santib/ar2dto/workflows/CI/badge.svg)
 
@@ -10,17 +10,27 @@ AR2DTO (ActiveRecord to DTO, pronounced R2-D2 or Artoo-Detoo) is a gem that lets
   - [Why AR2DTO?](#why-ar2dto)
 - [Installation](#installation)
 - [Usage](#usage)
+  - [Global configuration](#global-configuration)
   - [Setting up your models](#setting-up-your-models)
+  - [DTO class](#dto-class)
+  - [#to_dto](#to_dto)
+  - [.to_dto](#to_dto-1)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
 - [Code of Conduct](#code-of-conduct)
 
 ## Motivation
-TBD
+
+ActiveRecord is a very powerful tool and extensively used in most Rails apps. When working on large Rails apps, having such powerful objects all over the place can have a negative impact on the maintainability of the app. This is even more clear when trying to create domain boundaries within a Rails monolith. When there is communication between different components you probably don't want to share an ActiveRecord model with other components, if you do that, you'll be giving direct access to your component's tables from anywhere. For that reason, we want to create POROs that look like ActiveRecord models but that are much simpler and only carry data. This could be done by hand, but with this gem, we are trying to help you avoid having to write all the boilerplate to create these objects. As a corollary, by using this gem you are standardizing how things are done, and how your data-only objects look like.
 
 ### Why AR2DTO?
-TBD
+
+- It lets you work with objects that are similar to ActiveRecord models but without DB access or business logic.
+- It impedes ActiveRecord models leaking through its methods.
+- It helps you reduce boilerplate.
+- It provides a standard way to work with data-only objects.
+- It is a very small gem focused on solving one specific problem.
 
 ## Installation
 
@@ -39,10 +49,115 @@ Or install it yourself as:
     $ gem install ar2dto
 
 ## Usage
-TBD
+
+In the following sections, we explain the API provided by the gem and some basic usage.
+
+Many aspects of AR2DTO are [configurable for individual models](#setting-up-your-models); typically this is achieved by passing options to the has_dto method within a given model. Some aspects of AR2DTO are [configured globally](#global-configuration) for all models.
+
+### Global Configuration
+Global configuration options affect all threads and models where has_dto has been defined. A common place to put these settings is in a Rails initializer file such as `config/initializers/ar2dto.rb`.
+These settings are assigned directly on the `AR2DTO.configure` object.
+
+Configuration options are:
+ - `active_model_compliace`: DTO objects behaves like `ActiveModel` objects to play well with other parts of Rails and its ecosystem. Defaults to `true`.
+ - `except`: array of attributes to exclude from the DTO. Defaults to `[]`.
+ - `delete_suffix`: suffix to be delete from the model name. Defaults to `nil`.
+ - `add_suffix`: suffix to be added to the model name. Defaults to `"DTO"`.
+
+Syntax examples:
+
+```ruby
+  # config/initializers/ar2dto.rb
+
+  AR2DTO.configure do |config|
+    config.active_model_compliance = true
+    config.except = [:updated_at]
+    config.delete_suffix = nil
+    config.add_suffix = "DTO"
+  end
+```
+
+OR
+
+```ruby
+  # config/initializers/ar2dto.rb
+
+  AR2DTO.configure.active_model_compliance = true
+  AR2DTO.configure.except = [:updated_at]
+  AR2DTO.configure.delete_suffix = nil
+  AR2DTO.configure.add_suffix = "DTO"
+```
+
+These options are intended to be set only once, during app initialization.
 
 ### Setting up your models
-TBD
+
+To use the gem, you need to add `has_dto` to your ActiveRecord models. For example:
+```ruby
+class User < ApplicationRecord
+  has_dto
+end
+```
+
+This will dynamically create a class called `UserDTO` and will add two methods to your ActiveRecord model: [#to_dto](#to_dto) and [.to_dto](#to_dto-1).
+
+### DTO class
+
+This class is dynamically created based on your models that declare `has_dto`. The goal of these classes is to be data-only. They don't have access to the DB, business logic, or calculate things on the fly. They just store the data and provide them in a read-only fashion through plain simple methods.
+
+In addition to that, and optionally, you can have these objects be compliant with the [ActiveModel API](https://github.com/rails/rails/blob/main/activemodel/lib/active_model/lint.rb), you can do that by configuring it globally with:
+
+```ruby
+# config/initializers/ar2dto.rb
+
+AR2DTO.configure do |config|
+  config.active_model_compliance = true
+end
+```
+
+With this, it'll be even easier to interchange ActiveRecord models for DTOs, because other parts of Rails and other gems will continue to work (e.g. Rails route helpers).
+
+### #to_dto
+
+When calling `#to_dto` on an ActiveRecord model, a DTO object will be initialized with the model attributes. As an example:
+
+```ruby
+user = User.create!(name: 'John', email: 'john@example.com')
+user_dto = user.to_dto
+# #<UserDTO:0x00007fab8ce66a10 @name="John" @email="john@example.com">
+```
+
+`user_dto` will be an instance of `UserDTO` and, by default, it will be initialized with the same attributes as the model, that is: `id`, `name`, `email`, `created_at`, and `updated_at`.
+
+You can then use `user_dto` across your app, and even share it with other components, without having to worry about others making queries, modifying data, or even running business logic, where they shouldn't.
+
+This method accepts the same options as `ActiveRecord`'s `#as_json`, they are `except`, `only`, `methods`, and `include`.
+
+`except`
+Excludes attributes from the model when creating the DTO.
+
+`only`
+Selects the only attributes that should be included when creating the DTO.
+
+`methods`
+Run methods defined in the model and stores the values into the DTO as attributes.
+
+`include`
+Includes an association into the DTO. The association is also converted into a DTO in case of a `has_one`/`belongs_to` association, or into an `Array` of DTOs in case of a `has_many` association. The associations accepts the same options explained above.
+
+### .to_dto
+
+This method is similar to `#to_dto` but meant for `ActiveRecord::Relation`. So that running:
+
+```ruby
+User.last(10).to_dto
+```
+
+will return an `Array` consisting of 10 `UserDTO`. With this you are forcing the executing of the query, having collections of simple data objects, and avoiding other parts of the app from modifying the query.
+
+It accepts the same options as `#to_dto` and uses them create each DTO.
+
+:warning: **Warning!** Given that this method executes the query and brings records into memory, you have to be careful when and how to use it. You may not want to bring all records from a large table into memory. Consider combining it with things such as pagination or batch processing.
 
 ## Development
 

data/lib/ar2dto/active_model.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module AR2DTO
+  module ActiveModel
+    def self.included(base)
+      base.include ::ActiveModel::Conversion
+      base.extend ::ActiveModel::Naming
+      base.extend ::ActiveModel::Translation
+      base.extend ::AR2DTO::ActiveModel::ClassMethods
+
+      base.class_eval do
+        def persisted?
+          id.present?
+        end
+
+        def errors
+          @errors ||= ::ActiveModel::Errors.new(self.class.original_model)
+        end
+
+        def to_partial_path
+          self.class.original_model._to_partial_path
+        end
+      end
+    end
+
+    module ClassMethods
+      def model_name
+        ::ActiveModel::Name.new(original_model)
+      end
+    end
+  end
+end

data/lib/ar2dto/config.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AR2DTO
+  class Config
+    include Singleton
+
+    def self.reset!
+      instance.active_model_compliance = true
+      instance.except = []
+      instance.delete_suffix = nil
+      instance.add_suffix = "DTO"
+    end
+
+    attr_accessor :active_model_compliance, :except, :delete_suffix, :add_suffix
+
+    def initialize
+      @active_model_compliance = true
+      @except = []
+      @delete_suffix = nil
+      @add_suffix = "DTO"
+    end
+  end
+end

data/lib/ar2dto/converter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module AR2DTO
+  class Converter
+    attr_reader :model, :options
+
+    def initialize(model, options)
+      @model = model
+      @options = apply_configs(options)
+    end
+
+    def serializable_hash
+      hash = model.serializable_hash(options&.except(:methods, :include))
+      hash = add_methods(hash)
+      add_associations(hash)
+    end
+
+    private
+
+    def apply_configs(options)
+      options[:except] = Array(model.class.ar2dto.except) | Array(options[:except])
+      options
+    end
+
+    def add_methods(hash)
+      options&.dig(:methods)&.each do |method|
+        result = model.send(method)
+        result = if result.respond_to?(:to_dto)
+                   result.to_dto
+                 else
+                   result.as_json
+                 end
+        hash[method.to_s] = result
+      end
+      hash
+    end
+
+    def add_associations(hash)
+      includes.each do |association, opts|
+        records = model.send(association)
+        hash[association.to_s] = records ? records_dto(records, opts) : nil
+      end
+      hash
+    end
+
+    def includes
+      includes = options&.dig(:include)
+      return includes if includes.is_a?(Hash)
+
+      Array(includes).flat_map { |n| n.is_a?(Hash) ? n.to_a : [[n, {}]] }.to_h
+    end
+
+    def records_dto(records, opts)
+      if records.respond_to?(:to_ary)
+        records.to_ary.map { |a| a.to_dto(opts) }
+      else
+        records.to_dto(opts)
+      end
+    end
+  end
+end

data/lib/ar2dto/dto.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module AR2DTO
+  class DTO
+    def self.[](original_model)
+      Class.new(self) do
+        include ::AR2DTO::ActiveModel if original_model.ar2dto.active_model_compliance
+        define_singleton_method(:original_model) { original_model }
+      end
+    end
+
+    def initialize(attributes = {})
+      attributes.each { |key, value| define_singleton_method(key) { value } }
+      super()
+    end
+
+    def as_json(options = nil)
+      attribute_names = self.class.original_model.attribute_names
+      attribute_names.map { |name| [name.to_sym, send(name)] }.to_h.as_json(options)
+    end
+
+    def ==(other)
+      if other.instance_of?(self.class)
+        as_json == other.as_json
+      else
+        super
+      end
+    end
+  end
+end

data/lib/ar2dto/has_dto.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AR2DTO
+  # Extensions to `ActiveRecord::Base`.
+  module HasDTO
+    def self.included(base)
+      base.extend ::AR2DTO::HasDTO::ClassMethods
+    end
+
+    module ClassMethods
+      # Declare this in your model to expose the DTO helpers.
+      #
+      # @api public
+      def has_dto(options = {})
+        include ::AR2DTO::HasDTO::InstanceMethods
+        ar2dto.setup_config(options)
+
+        begin
+          ar2dto.namespaced_class_name.constantize
+        rescue NameError
+          ar2dto.namespace.const_set(ar2dto.class_name, AR2DTO::DTO[self])
+        end
+      end
+
+      # @api public
+      def to_dto(options = {})
+        all.map { |record| record.to_dto(options) }
+      end
+
+      # @api public
+      def ar2dto
+        @ar2dto ||= AR2DTO::ModelConfig.new(self)
+      end
+    end
+
+    # Wrap the following methods in a module so we can include them only in the
+    # ActiveRecord models that declare `has_dto`.
+    module InstanceMethods
+      # @api public
+      def to_dto(options = {})
+        self.class.ar2dto.namespaced_class_name.constantize.new(
+          AR2DTO::Converter.new(self, options).serializable_hash
+        )
+      end
+    end
+  end
+end

data/lib/ar2dto/model_config.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module AR2DTO
+  class ModelConfig
+    attr_reader :model, :model_config
+
+    def initialize(model)
+      @model = model
+    end
+
+    def setup_config(model_config)
+      @model_config ||= model_config
+    end
+
+    def active_model_compliance
+      @active_model_compliance ||= global_config.active_model_compliance
+    end
+
+    def except
+      @except ||= Array(global_config.except) | Array(model_config[:except])
+    end
+
+    def class_name
+      @class_name ||= namespaced_class_name.split("::").last
+    end
+
+    def namespace
+      @namespace ||= namespaced_class_name.deconstantize.presence&.constantize || Object
+    end
+
+    def namespaced_class_name
+      @namespaced_class_name ||= model_config[:class_name] || model_name_replaced_suffix
+    end
+
+    private
+
+    def model_name_replaced_suffix
+      "#{model.name.delete_suffix(global_config.delete_suffix.to_s)}#{global_config.add_suffix}"
+    end
+
+    def global_config
+      AR2DTO::Config.instance
+    end
+  end
+end

data/lib/ar2dto.rb

@@ -1,8 +1,25 @@
 # frozen_string_literal: true
 
+require "active_record"
+require "active_model"
+require "singleton"
+
+require_relative "ar2dto/active_model"
+require_relative "ar2dto/dto"
+require_relative "ar2dto/config"
+require_relative "ar2dto/converter"
+require_relative "ar2dto/model_config"
 require_relative "ar2dto/version"
+require_relative "ar2dto/has_dto"
+
+ActiveRecord::Base.include ::AR2DTO::HasDTO
 
 module AR2DTO
   class Error < StandardError; end
-  # Your code goes here...
+
+  def self.configure
+    @config ||= AR2DTO::Config.instance
+    yield @config if block_given?
+    @config
+  end
 end

metadata

@@ -1,15 +1,31 @@
 --- !ruby/object:Gem::Specification
 name: ar2dto
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Santiago Bartesaghi
+- Martín Jaime Morón
+- Sebastian Herrera
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-06-05 00:00:00.000000000 Z
+date: 2022-07-07 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -24,9 +40,95 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner-active_record
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.8.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.8.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.1
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.9.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.9.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.28.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.28.2
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.2
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.6.0
 description:
 email:
 - santib@hey.com
+- martinmoron7@gmail.com
+- sebaherrera93@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -34,7 +136,12 @@ files:
 - LICENSE.txt
 - README.md
 - lib/ar2dto.rb
-- lib/ar2dto/base.rb
+- lib/ar2dto/active_model.rb
+- lib/ar2dto/config.rb
+- lib/ar2dto/converter.rb
+- lib/ar2dto/dto.rb
+- lib/ar2dto/has_dto.rb
+- lib/ar2dto/model_config.rb
 - lib/ar2dto/version.rb
 homepage: https://github.com/santib/ar2dto
 licenses:
@@ -44,6 +151,7 @@ metadata:
   source_code_uri: https://github.com/santib/ar2dto
   bug_tracker_uri: https://github.com/santib/ar2dto/issues
   changelog_uri: https://github.com/santib/ar2dto/releases
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -59,7 +167,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Easing the creation of DTOs from your ActiveRecord models.

data/lib/ar2dto/base.rb

@@ -1,26 +0,0 @@
-module AR2DTO
-  module Base
-    def self.included(model)
-      namespace = model.name.deconstantize.presence&.constantize || Object
-
-      namespace.const_set("#{model.name.split('::').last}DTO", Class.new do
-        include ::ActiveModel::Model
-        attr_reader :attributes
-        attr_accessor *model.column_names
-
-        def initialize(attributes)
-          @attributes = attributes
-          super
-        end
-
-        def ==(other)
-          attributes == other.attributes
-        end
-      end)
-    end
-
-    def to_dto
-      "#{self.class.name}DTO".constantize.new(attributes)
-    end
-  end
-end