pretty-api 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e020194708396186f0a862e8fcdfe24b4bba1d9ce4449f7261bef0c2a76451d2
+  data.tar.gz: fdf19f29e2a101b15a6f2bf4e48fcc84a5ae5bef7469c2eeea6490272cbe66e5
+SHA512:
+  metadata.gz: 3a4a6b834fc2d8b2c27be2d27bae71b6c366584227071299dcdf0fbd58fcde1d9225a9051dc470acfbe1213bed65e8556eb7c4cc6dd03df83f2df2f233b3a9ca
+  data.tar.gz: 883fd45dfb069e6fe71cde4603265ebab372bfbf0f64007b3aa1e76b164c1a9fdec5f5b143799162a0f8d4477746ea0c33d999b02b569af28bbe99808e92c6ab

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,112 @@
+inherit_gem:
+  rubocop-rails-omakase: rubocop.yml
+
+inherit_mode:
+  merge:
+    - Exclude
+
+require:
+  - rubocop-rails
+  - rubocop-performance
+  - rubocop-rspec
+
+AllCops:
+  DisabledByDefault: false
+  DisplayCopNames: true
+  NewCops: enable
+  Exclude:
+    - config/initializers/devise.rb
+    - lib/templates/**/*
+    - public/**/*
+
+FactoryBot/ConsistentParenthesesStyle:
+  EnforcedStyle: omit_parentheses
+
+Layout/LineLength:
+  Exclude:
+    - config/initializers/simple_form_bootstrap.rb
+
+Layout/SpaceInsideArrayLiteralBrackets:
+  Enabled: true
+  EnforcedStyle: no_space
+  EnforcedStyleForEmptyBrackets: no_space
+
+Lint/EmptyBlock:
+  Enabled: false
+
+Lint/UnusedBlockArgument:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 20
+  Exclude:
+    - db/migrate/**/*
+    - db/seed/**/*
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/MethodLength:
+  Max: 15
+  Exclude:
+    - db/migrate/**/*
+    - null
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+RSpec/AnyInstance:
+  Enabled: false
+
+RSpec/EmptyExampleGroup:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Max: 10
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Enabled: false
+
+RSpec/RepeatedExample:
+  Enabled: false
+
+Rails/NotNullColumn:
+  Enabled: false
+
+Rails/OutputSafety:
+  Exclude:
+    - app/decorators/**/*
+    - app/helpers/**/*
+
+Style/Documentation:
+  Enabled: false
+
+Style/EmptyMethod:
+  EnforcedStyle: expanded
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Layout/IndentationConsistency:
+  Enabled: true
+  EnforcedStyle: normal
+
+Layout/IndentationWidth:
+  Enabled: true
+  Width: 2
+
+Layout/MultilineMethodCallIndentation:
+  Enabled: true
+  EnforcedStyle: indented_relative_to_receiver
+
+Gemspec/RequireMFA:
+  Enabled: false

data/.standalone_migrations

@@ -0,0 +1,6 @@
+db:
+    seeds: spec/app/db/seeds.rb
+    migrate: spec/app/db/migrate
+    schema: spec/app/db/schema.rb
+config:
+    database: spec/app/db/config.yml

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-05-30
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 James St-Pierre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,194 @@
+# PrettyApi
+
+Build API that feels like home using native built in Ruby on Rails and ActiveRecord `accepts_nested_attributes_for` but
+without all the boilerplate code that makes your Javascript dirty.
+
+## Comparison
+
+Exemple with an organization that has 2 services. Let's say we would like to update one service and destroy the other.
+
+#### Without PrettyAPI
+
+```json
+{
+  "organization": {
+    "id": 1,
+    "services_attributes": [
+      {
+        "id": 1,
+        "name": "Service to destroy",
+        "_destroy": true
+      },
+      {
+        "id": 2,
+        "name": "Service to update"
+      }
+    ]
+  }
+}
+```
+
+### With PrettyAPI
+
+You can omit `_attributes` from your attributes and you can omit everything that you would like to destroy as well.
+
+```json
+{
+  "organization": {
+    "id": 1,
+    "services": [
+      {
+        "id": 2,
+        "name": "Service to update"
+      }
+    ]
+  }
+}
+```
+
+More exemples
+
+```javascript
+{
+  organization: {
+    services: [] // Delete all services
+  }
+  
+  organization: {
+    // Fully omit "services" attribute to leave as is
+  }
+}
+```
+
+## How it works
+
+Because Rails is a framework built on conventions over configurations, it is possible to use reflections on your
+ActiveRecord models to automatically detect which attributes are expected to be "nested" by declaring properly your
+nested attributes using `accepts_nested_attributes_for`.
+
+## Why
+
+In the past I have built many applications that were using frontend frameworks such as React, VueJS and Svelte built on
+top of a Ruby on Rails API. Here are the things that always have irritated me
+
+1. Transforming all my attributes to `_attributes` when the time comes to send my data to the API.
+2. Keeping destroyed objects in my Arrays only to tell Rails to destroy them by sending `{ id: 1, _destroy: true }`
+
+I have tried the approach of working directly with object instances but ActiveRecord behaves unexpectedly by saving
+every associations as soon as you assign the parameters. Here is an exemple
+
+```
+params[:services]
+=> { services: [] }
+
+@organization.assign_attributes(params)
+=> DELETE FROM services WHERE organization_id = 1;
+```
+
+You don't even have time to check for validation or do anything that ActiveRecord already destroyed every services in
+the database that belongs to your organization.
+
+## Installation
+
+Add this line to your Gemfile:
+
+    gem "pretty-api"
+
+## Configuration
+
+You can optionally create an initializer to configure these options
+```
+# Destroy associations that are omitted in your payload
+PretttyApi.destroy_missing_associations = true
+```
+
+## Usage
+
+```
+class OrganizationsController < ApplicationController
+  include PrettyApi::Helpers
+
+  def create
+    @organization = Organization.new
+    @organization.assign_attributes(pretty_nested_attributes(@organization, organization_params))
+    ...
+  end
+  
+  def update
+    @organization = Organization.find(...)
+    @organization.assign_attributes(pretty_nested_attributes(@organization, organization_params))
+    ...
+  end
+
+  private
+  
+  def organization_params
+    params.require(:organization).permit(:name, services: [:id, :name])
+  end
+end
+```
+
+## This gem needs more testing
+
+While this gem has some unit tests, it hasn't been battle tested yet.
+
+## Beta feature
+
+This is a new feature that I am testing to see if I can make validation errors
+over API way easier to work with. By default ActiveRecord doesn't tell you which records in your
+associations are invalid. This is making very hard to highlight the proper input field
+in forms when you are working with nested forms.
+
+```
+include PrettyApi::Helpers
+
+@organization.valid?
+=> false
+
+pretty_nested_errors(@organization)
+=> {
+  name: ["can't be blank"],
+  organizations: {
+    1 => { name: ["can't be blank"] }
+    3 => { name: ["can't be blank"] }
+  }
+}
+```
+
+Note: There is a "somewhat" similar feature in ActiveRecord that is not well documented.
+However, while the keys are indexed, they are in string format making it hard
+to work with.
+
+```
+# Per association: 
+has_many :my_associations, index_errors: true
+
+# Globally:
+config.active_record.index_nested_attribute_errors = true
+
+# Before
+product.error.messages
+=> {:"variants.display_name"=>["can't be blank"], :"variants.price"=>["can't be blank"]}
+
+# After
+product.error.messages
+{:"variants[0].display_name"=>["can't be blank"], :"variants[1].price"=>["can't be blank"]}
+```
+
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rspec` to run the tests.
+
+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/jamesst20/pretty_api.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+require 'standalone_migrations'
+
+StandaloneMigrations::Tasks.load_tasks
+
+task default: :spec

data/internal.md

@@ -0,0 +1,25 @@
+# Internal documentation
+
+This documentation is not meant to be read by anybody. This document will be used for self documentations
+to avoid forgetting important implementations motivations.
+
+This gem can get a little confusing sometimes because `accepts_nested_attributes_for` can be used with any kind
+of associations (has_many, belongs_to, has_one, has_many_though, ...) and it can also be used to self reference itself
+or another association that reference itself. We must handle properly these use case to avoid infinite loop.
+
+We are able to extract the dependency tree of an association with the internal method `nested_attributes_tree`. This
+method is implemented in two formats: one that returns an array structure, one that returns an hash structure. The library
+itself doesn't make any use of two formats, however we do want to support to type of structure for better user
+experience and compatibility. This is mostly useful for unit testings but this allow users to use the structure they
+want when they pass manually the association tree to the public helpers method.
+
+### Notes on the pretty nested attributes implementation
+
+We must never rely on parameters indexes to extract a record association. The order is not guaranteed and this could 
+lead to odd behavior or potential accidental data loss. We must rely on the primary key of the record against the
+given parameter. If not done properly, it would append in the parameters `{ id: ..., _destroy: true}` wrongly thinking
+some associations dont exist. I believe ActiveRecord would raise a RecordNotFound exception to protect against this
+scenario, however we have unit tests to protect against this scenario to avoid code regression in the future.
+
+Internally it infers automatically the dependency tree of a record by calling `nested_attributes_tree` or by receiving
+an hash or an array by the user explicitly. This is subject to the spoken hash or array format spoken earlier.

data/lib/pretty-api.rb

@@ -0,0 +1 @@
+require_relative "pretty_api" # rubocop:disable Naming/FileName

data/lib/pretty_api/active_record/associations.rb

@@ -0,0 +1,73 @@
+module PrettyApi
+  module ActiveRecord
+    class Associations
+      def self.nested_attributes_tree(model, structure = :array)
+        if structure == :array
+          nested_attributes_tree_array(model)
+        elsif structure == :hash
+          nested_attributes_tree_hash(model)
+        end
+      end
+
+      def self.nested_attributes_tree_hash(model, depth = {})
+        nested_attributes_descriptions(model).index_by { |a| a[:id] }.each_with_object({}) do |(key, assoc), result|
+          depth[key] ||= 0
+
+          next unless depth[key] < PrettyApi.max_nested_attributes_depth
+
+          depth[key] += 1
+          result[assoc[:name]] = nested_attributes_tree_hash(assoc[:model], depth)
+          depth[key] -= 1
+        end
+      end
+
+      def self.nested_attributes_tree_array(model, depth = {})
+        nested_attributes_descriptions(model).index_by { |a| a[:id] }.map do |(key, association)|
+          depth[key] ||= 0
+
+          next nil if depth[key] >= PrettyApi.max_nested_attributes_depth
+
+          depth[key] += 1
+          result = { association[:name] => nested_attributes_tree_array(association[:model], depth) }
+          depth[key] -= 1
+
+          result.compact_blank.blank? ? association[:name] : result
+        end.compact_blank
+      end
+
+      def self.nested_attributes_descriptions(model)
+        model.nested_attributes_options.keys.map do |association_name|
+          association_model = attribute_association_class(model, association_name)
+          {
+            id: "#{model}_#{association_name}",
+            name: association_name,
+            model: association_model,
+            associations: association_model.nested_attributes_options.keys.map do |n|
+              attribute_association_class(association_model, n)
+            end
+          }
+        end
+      end
+
+      def self.attribute_destroy_allowed?(model, attribute)
+        model.nested_attributes_options[attribute.to_sym][:allow_destroy] == true
+      end
+
+      def self.attribute_association(model, attribute)
+        model.reflect_on_association(attribute).chain.last
+      end
+
+      def self.attribute_association_class(model, attribute)
+        model.reflect_on_association(attribute).class_name.constantize
+      end
+
+      def self.association_type(association)
+        association.macro
+      end
+
+      def self.association_primary_key(association)
+        association.class_name.constantize.primary_key
+      end
+    end
+  end
+end

data/lib/pretty_api/active_record/orm.rb

@@ -0,0 +1,9 @@
+module PrettyApi
+  module ActiveRecord
+    class Orm
+      def self.where_not(record, attribute, values)
+        record.where.not(attribute => values)
+      end
+    end
+  end
+end

data/lib/pretty_api/errors/nested_errors.rb

@@ -0,0 +1,58 @@
+module PrettyApi
+  module Errors
+    class NestedErrors
+      def self.parsed_nested_errors(record, attrs)
+        errors = record_only_errors(record)
+
+        return errors if attrs.blank?
+
+        parse_deep_nested_errors(record, attrs, errors)
+
+        PrettyApi::Utils::Hash.deep_compact_blank(errors)
+      end
+
+      def self.parse_deep_nested_errors(record, attrs, result, parent_record = nil)
+        case attrs
+        when Hash
+          attrs.each do |key, value|
+            parse_association_errors(record, key, value, result, parent_record)
+          end
+        when Array
+          attrs.each { |value| parse_deep_nested_errors record, value, result, parent_record }
+        else
+          parse_association_errors(record, attrs, nil, result, parent_record)
+        end
+      end
+
+      def self.parse_association_errors(record, attr, nested_attrs, result, parent_record)
+        association = record.send(attr)
+
+        return if association.blank?
+        return if association == parent_record
+
+        if association.respond_to? :to_a
+          parse_has_many_errors(record, association, attr, nested_attrs, result)
+        else
+          parse_has_one_errors(record, association, attr, nested_attrs, result)
+        end
+      end
+
+      def self.parse_has_many_errors(record, associations, attr, nested_attrs, result)
+        result[attr] = {}
+        associations.each_with_index do |association, i|
+          result[attr][i] = record_only_errors(association)
+          parse_deep_nested_errors association, nested_attrs, result[attr][i], record if nested_attrs.present?
+        end
+      end
+
+      def self.parse_has_one_errors(record, association, attr, nested_attrs, result)
+        result[attr] = record_only_errors(association)
+        parse_deep_nested_errors association, nested_attrs, result[attr], record if nested_attrs.present?
+      end
+
+      def self.record_only_errors(record)
+        record.errors.as_json.reject { |k, _v| k.to_s.include?(".") }
+      end
+    end
+  end
+end

data/lib/pretty_api/helpers.rb

@@ -0,0 +1,21 @@
+module PrettyApi
+  module Helpers
+    extend ActiveSupport::Concern
+
+    included do
+      def pretty_nested_attributes(record, params, attrs = nil)
+        params = params.to_h.with_indifferent_access
+
+        attrs ||= PrettyApi::ActiveRecord::Associations.nested_attributes_tree(record.class)
+
+        PrettyApi::Parameters::NestedAttributes.parse_nested_attributes(record, params, attrs)
+      end
+
+      def pretty_nested_errors(record, attrs = nil)
+        attrs ||= PrettyApi::ActiveRecord::Associations.nested_attributes_tree(record.class)
+
+        PrettyApi::Errors::NestedErrors.parsed_nested_errors(record, attrs)
+      end
+    end
+  end
+end

data/lib/pretty_api/parameters/nested_attributes.rb

@@ -0,0 +1,82 @@
+module PrettyApi
+  module Parameters
+    class NestedAttributes
+      def self.parse_nested_attributes(record, params, attrs)
+        return {} if params.blank?
+
+        case attrs
+        when Hash, Array
+          parse_deep_nested_attributes(record, params, attrs)
+        when String, Symbol
+          if params.key?(attrs)
+            include_associations_to_destroy(record, params, attrs)
+            params["#{attrs}_attributes"] = params.delete(attrs)
+          end
+        end
+
+        params
+      end
+
+      def self.parse_deep_nested_attributes(record, params, attrs)
+        case attrs
+        when Hash
+          attrs.each do |assoc_key, nested_assoc|
+            if params[assoc_key].is_a? Array
+              parse_has_many_association(record, params, assoc_key, nested_assoc)
+            else
+              parse_has_one_association(record, params, assoc_key, nested_assoc)
+            end
+            parse_nested_attributes(record, params, assoc_key)
+          end
+        when Array
+          attrs.each { |assoc_or_nested_assoc| parse_nested_attributes(record, params, assoc_or_nested_assoc) }
+        end
+      end
+
+      def self.parse_has_many_association(record, params, assoc_key, nested_assoc)
+        params[assoc_key].each do |p|
+          assoc_primary_key = record.try(:class).try(:primary_key)
+          assoc = record.try(assoc_key).try(:detect) { |r| r.try(assoc_primary_key) == p[assoc_primary_key] }
+          parse_nested_attributes(assoc, p, nested_assoc)
+        end
+      end
+
+      def self.parse_has_one_association(record, params, assoc_key, nested_assoc)
+        parse_nested_attributes(record.try(assoc_key), params[assoc_key], nested_assoc)
+      end
+
+      def self.include_associations_to_destroy(record, params, attr)
+        return unless PrettyApi.destroy_missing_associations && record.present?
+
+        association = PrettyApi::ActiveRecord::Associations.attribute_association(record.class, attr)
+
+        return unless PrettyApi::ActiveRecord::Associations.attribute_destroy_allowed?(record.class, attr)
+
+        primary_key = PrettyApi::ActiveRecord::Associations.association_primary_key(association)
+
+        assoc_type = PrettyApi::ActiveRecord::Associations.association_type(association)
+
+        include_has_many_to_destroy(record, params, attr, primary_key) if assoc_type == :has_many
+        include_has_one_to_destroy(record, params, attr, primary_key) if assoc_type.in?(%i[has_one belongs_to])
+      end
+
+      def self.include_has_many_to_destroy(record, params, attr, primary_key)
+        ids_to_destroy = PrettyApi::ActiveRecord::Orm
+                           .where_not(record.send(attr), primary_key, params[attr].pluck(primary_key))
+                           .pluck(primary_key)
+
+        params[attr].push(*ids_to_destroy.map { |id| { primary_key => id, _destroy: true } })
+      end
+
+      def self.include_has_one_to_destroy(record, params, attr, primary_key)
+        association_id = record.send(attr).try(primary_key)
+
+        return if association_id.blank?
+        return if params[attr].try(:[], primary_key).present?
+
+        params[attr] ||= {}
+        params[attr].merge!({ primary_key => association_id, _destroy: true })
+      end
+    end
+  end
+end

data/lib/pretty_api/utils/hash.rb

@@ -0,0 +1,13 @@
+module PrettyApi
+  module Utils
+    class Hash
+      def self.deep_compact_blank(hash)
+        hash.each_with_object({}) do |(k, v), new_hash|
+          v = deep_compact_blank(v) if v.is_a? ::Hash
+          v = v.compact_blank if v.is_a? ::Array
+          new_hash[k] = v if v.present?
+        end
+      end
+    end
+  end
+end

data/lib/pretty_api/version.rb

@@ -0,0 +1,3 @@
+module PrettyApi
+  VERSION = "0.2.0".freeze
+end

data/lib/pretty_api.rb

@@ -0,0 +1,17 @@
+require "active_support/concern"
+
+require_relative "pretty_api/version"
+require_relative "pretty_api/utils/hash"
+require_relative "pretty_api/active_record/orm"
+require_relative "pretty_api/errors/nested_errors"
+require_relative "pretty_api/helpers"
+require_relative "pretty_api/active_record/associations"
+require_relative "pretty_api/parameters/nested_attributes"
+
+module PrettyApi
+  singleton_class.attr_accessor :destroy_missing_associations
+  self.destroy_missing_associations = true
+
+  singleton_class.attr_accessor :max_nested_attributes_depth
+  self.max_nested_attributes_depth = 1
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: pretty-api
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- James St-Pierre
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-06-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Simplify the usage of accepts_nested_attributes_for in Rails applications.
+email:
+- Jamesst20@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".standalone_migrations"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- internal.md
+- lib/pretty-api.rb
+- lib/pretty_api.rb
+- lib/pretty_api/active_record/associations.rb
+- lib/pretty_api/active_record/orm.rb
+- lib/pretty_api/errors/nested_errors.rb
+- lib/pretty_api/helpers.rb
+- lib/pretty_api/parameters/nested_attributes.rb
+- lib/pretty_api/utils/hash.rb
+- lib/pretty_api/version.rb
+homepage: https://github.com/jamesst20/pretty_api
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jamesst20/pretty_api
+  source_code_uri: https://github.com/jamesst20/pretty_api
+  changelog_uri: https://github.com/jamesst20/pretty_api/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Pretty API for Rails
+test_files: []