jpie 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8d19fff52264fdefbdba8d63bae64a532cbd2daddfdcfbfaa9ffd205d028822
-  data.tar.gz: c10827822e1638a8e0690a8432709a0cfc7d3fc5d82a845e276d74c66f8761c3
+  metadata.gz: 4e425e58d806e51b4cb6ed58345acdc3169079011dca02fa8dfae18b57bbe70c
+  data.tar.gz: e0f9316d7a675048c5c63442e9f897452ffa62358d3ca73d8e8aa288122a623c
 SHA512:
-  metadata.gz: 7693f48c7c20c4879478a72e233c092dd4e0a90e1ca038129b3c3d2821d2d07d0cfa50bd73b166c2c5235e2e580869b989fce91928916b2df671e397811002d7
-  data.tar.gz: 859af674c3a0eca429e86ed566df855141806b1d26d15f7dacfa2fad5ab93699957a9c30e218199bb04152b6ab865e690c0ed1cf54296ebc9fe58de0fd967dc2
+  metadata.gz: 36c41c6de0027699b5534abe379930f67fc67698aa8016635a294b8ba5624ace0bedaeaebddfbf5708c3ad58696527b1e15f177ac84c36c272581cff123a52ec
+  data.tar.gz: c948938233596ef3345bc7186e8f78575f37c1057d9675850634ddb53c36506de7b26b89f14555fdca8659124ae8ec0b9908da39324f87cff90dd82aa2c8cd8d

data/Gemfile

@@ -19,5 +19,6 @@ group :development, :test do
   gem "rubocop-performance", "~> 1.0"
   gem "rubocop-rails", "~> 2.0"
   gem "rubocop-rspec", "~> 3.0"
+  gem "simplecov", "~> 0.22", require: false
   gem "sqlite3", ">= 2.1"
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jpie (1.0.1)
+    jpie (1.1.0)
       actionpack (~> 8.0, >= 8.0.0)
       rails (~> 8.0, >= 8.0.0)
 
@@ -95,6 +95,7 @@ GEM
     crass (1.0.6)
     date (3.5.0)
     diff-lcs (1.6.2)
+    docile (1.4.1)
     drb (2.2.3)
     erb (6.0.0)
     erubi (1.13.1)
@@ -266,6 +267,12 @@ GEM
       rubocop (~> 1.81)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
     simpleidn (0.2.3)
     sqlite3 (2.8.0-aarch64-linux-gnu)
     sqlite3 (2.8.0-aarch64-linux-musl)
@@ -315,6 +322,7 @@ DEPENDENCIES
   rubocop-performance (~> 1.0)
   rubocop-rails (~> 2.0)
   rubocop-rspec (~> 3.0)
+  simplecov (~> 0.22)
   sqlite3 (>= 2.1)
 
 BUNDLED WITH

data/README.md

@@ -14,6 +14,7 @@ A Rails 8+ gem that provides JSON:API compliant routing DSL and generic JSON:API
 - Configurable pagination options
 - Content negotiation with Accept and Content-Type headers
 - Support for polymorphic and STI relationships
+- Namespace support for API versioning and modular organization
 
 ## Installation
 
@@ -679,6 +680,91 @@ This is useful when you need access to features available in `ActionController::
 
 **Note:** The configuration must be set before the gem's controllers are loaded. Set it in a Rails initializer that loads before `json_api` is required.
 
+### Namespace Support
+
+The gem supports namespaced resources, controllers, and models for API versioning or modular organization.
+
+#### Configuration Options
+
+```ruby
+JSONAPI.configure do |config|
+  # Type format in JSON:API responses: :flat (default), :prefixed, or :underscore
+  # :flat       -> "vendors" (namespace inferred from route context)
+  # :prefixed   -> "api/v1/vendors"
+  # :underscore -> "api_v1_vendors"
+  config.namespace_type_format = :flat
+
+  # Model mapping: :same_namespace (default) or :flat
+  # :same_namespace -> API::V1::VendorResource maps to API::V1::Vendor
+  # :flat           -> API::V1::VendorResource maps to Vendor
+  config.namespace_model_mapping = :same_namespace
+
+  # Fallback behavior when namespaced resource not found: true (default) or false
+  # When true, if API::V1::VendorResource not found, try VendorResource
+  config.namespace_fallback = true
+end
+```
+
+#### Namespaced Routes
+
+Use Rails' standard `namespace` or `scope` with `module:` to define namespaced JSON:API resources:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  namespace :api do
+    namespace :v1 do
+      jsonapi_resources :widgets
+    end
+  end
+end
+```
+
+This will:
+
+- Look for `API::V1::WidgetsController` (falls back to `JSONAPI::ResourcesController` if not found)
+- Load `API::V1::WidgetResource` (falls back to `WidgetResource` if `namespace_fallback: true`)
+- Pass `jsonapi_namespace: "api/v1"` to the controller
+
+#### Namespaced Resources
+
+Define resources within namespaces that match your route structure:
+
+```ruby
+# app/resources/api/v1/widget_resource.rb
+module API
+  module V1
+    class WidgetResource < JSONAPI::Resource
+      attributes :name, :description
+    end
+  end
+end
+```
+
+#### Per-Resource Type Format
+
+Override the global `namespace_type_format` for individual resources:
+
+```ruby
+class API::V1::WidgetResource < JSONAPI::Resource
+  self.type_format = :prefixed  # This resource will serialize as "api/v1/widgets"
+
+  attributes :name
+end
+```
+
+#### Explicit Model Class
+
+Override the automatic model class resolution:
+
+```ruby
+class API::V1::WidgetResource < JSONAPI::Resource
+  self.model_class = Widget  # Use flat Widget model regardless of config
+
+  attributes :name
+end
+```
+
 ## Authorization
 
 The gem provides two optional authorization hooks:
@@ -1182,8 +1268,7 @@ Content-Type: application/vnd.api+json
       "filename": "avatar.jpg",
       "content_type": "image/jpeg",
       "byte_size": 102400,
-      "checksum": "abc123...",
-      "url": "/rails/active_storage/blobs/.../avatar.jpg"
+      "checksum": "abc123..."
     },
     "links": {
       "self": "/active_storage_blobs/1",
@@ -1193,7 +1278,7 @@ Content-Type: application/vnd.api+json
 }
 ```
 
-The built-in `JSONAPI::ActiveStorageBlobResource` provides `filename`, `content_type`, `byte_size`, `checksum`, and `url` attributes, plus a download link.
+The built-in `JSONAPI::ActiveStorageBlobResource` provides `filename`, `content_type`, `byte_size`, and `checksum` attributes. The download URL is available via the `links.download` property.
 
 ### Attaching Files
 

data/Rakefile

@@ -6,3 +6,25 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+
+# Override release task to require OTP code
+# Usage: GEM_HOST_OTP_CODE=123456 rake release
+Rake::Task["release"].enhance do
+  # This runs after the original release task
+end
+
+Rake::Task["release"].prerequisites.unshift("release:require_otp")
+
+namespace :release do
+  task :require_otp do
+    unless ENV["GEM_HOST_OTP_CODE"]
+      abort <<~ERROR
+        ERROR: GEM_HOST_OTP_CODE environment variable is required for release.
+
+        Usage: GEM_HOST_OTP_CODE=123456 rake release
+
+        Get your OTP code from your authenticator app.
+      ERROR
+    end
+  end
+end

data/lib/json_api/configuration.rb

@@ -3,7 +3,8 @@
 module JSONAPI
   class Configuration
     attr_accessor :default_page_size, :max_page_size, :jsonapi_meta, :authorization_handler,
-                  :authorization_scope, :document_meta_resolver
+                  :authorization_scope, :document_meta_resolver,
+                  :namespace_type_format, :namespace_model_mapping, :namespace_fallback
 
     def initialize
       @default_page_size = 25
@@ -13,6 +14,9 @@ module JSONAPI
       @authorization_scope = nil
       @document_meta_resolver = ->(controller:) { {} } # rubocop:disable Lint/UnusedBlockArgument
       @base_controller_class = "ActionController::API"
+      @namespace_type_format = :flat
+      @namespace_model_mapping = :same_namespace
+      @namespace_fallback = true
     end
 
     def base_controller_class=(value)

data/lib/json_api/controllers/concerns/controller_helpers/resource_setup.rb

@@ -6,7 +6,7 @@ module JSONAPI
       extend ActiveSupport::Concern
 
       included do
-        attr_reader :resource_class, :model_class
+        attr_reader :resource_class, :model_class, :jsonapi_namespace
       end
 
       protected
@@ -15,8 +15,13 @@ module JSONAPI
         @resource_name = params[:resource_type].to_s.singularize
       end
 
+      def set_jsonapi_namespace
+        @jsonapi_namespace = params[:jsonapi_namespace].presence
+      end
+
       def set_resource_class
-        @resource_class = JSONAPI::ResourceLoader.find(params[:resource_type])
+        namespace = params[:jsonapi_namespace].presence
+        @resource_class = JSONAPI::ResourceLoader.find(params[:resource_type], namespace:)
         @model_class = @resource_class.model_class
       rescue JSONAPI::ResourceLoader::MissingResourceClass => e
         render_resource_not_found_error(e.message)

data/lib/json_api/controllers/concerns/resource_actions/resource_loading.rb

@@ -9,7 +9,8 @@ module JSONAPI
 
       def load_jsonapi_resource
         @resource_name = params[:resource_type]&.singularize
-        @resource_class = JSONAPI::ResourceLoader.find(@resource_name) if @resource_name
+        @jsonapi_namespace = params[:jsonapi_namespace].presence
+        @resource_class = JSONAPI::ResourceLoader.find(@resource_name, namespace: @jsonapi_namespace) if @resource_name
         @model_class = @resource_class.model_class if @resource_class
         @resource = @model_class.find(params[:id]) if params[:id] && @model_class
       rescue JSONAPI::ResourceLoader::MissingResourceClass

data/lib/json_api/resources/active_storage_blob_resource.rb

@@ -2,18 +2,10 @@
 
 module JSONAPI
   class ActiveStorageBlobResource < Resource
-    attributes :filename, :content_type, :byte_size, :checksum, :url
+    attributes :filename, :content_type, :byte_size, :checksum
 
     def self.model_class
       ::ActiveStorage::Blob
     end
-
-    def url
-      return nil unless resource.persisted?
-
-      Rails.application.routes.url_helpers.rails_blob_path(resource, only_path: true)
-    rescue StandardError
-      "/rails/active_storage/blobs/#{resource.signed_id}/#{resource.filename}"
-    end
   end
 end

data/lib/json_api/resources/concerns/model_class_helpers.rb

@@ -5,23 +5,42 @@ module JSONAPI
     module ModelClassHelpers
       extend ActiveSupport::Concern
 
+      module NamespaceResolution
+        def resolve_model_class_name
+          resource_name = name.sub(/Resource$/, "")
+          flat_namespace_mapping? ? resource_name.demodulize : resource_name
+        end
+
+        def flat_namespace_mapping?
+          JSONAPI.configuration.namespace_model_mapping == :flat
+        end
+
+        def resource_namespace
+          name.deconstantize.presence&.underscore
+        end
+      end
+
       class_methods do
+        include NamespaceResolution
+
+        attr_writer :model_class
+
         def resource_for_model(model_class)
-          resource_const = "#{model_class.name}Resource"
-          resource_const.safe_constantize if resource_const.respond_to?(:safe_constantize) || defined?(ActiveSupport)
+          "#{model_class.name}Resource".safe_constantize
         rescue NameError
           nil
         end
 
         def model_class
-          name.sub(/Resource$/, "").classify.constantize
+          return @model_class if defined?(@model_class) && @model_class
+
+          resolve_model_class_name.constantize
         end
 
         def safe_model_class
-          return nil unless respond_to?(:name) && name
-          return nil unless defined?(ActiveSupport)
+          return nil unless respond_to?(:name) && name && defined?(ActiveSupport)
 
-          name.sub(/Resource$/, "").classify.safe_constantize
+          resolve_model_class_name&.safe_constantize
         rescue NoMethodError
           nil
         end

data/lib/json_api/resources/resource.rb

@@ -16,6 +16,15 @@ module JSONAPI
     include Resources::MetaDsl
     include Resources::ModelClassHelpers
 
+    class << self
+      attr_accessor :type_format
+
+      def inherited(subclass)
+        super
+        subclass.type_format = type_format
+      end
+    end
+
     def initialize(record = nil, context = {})
       @record = record
       @context = context

data/lib/json_api/resources/resource_loader.rb

@@ -3,33 +3,82 @@
 module JSONAPI
   class ResourceLoader
     class MissingResourceClass < JSONAPI::Error
-      def initialize(resource_type)
-        super("Resource class for '#{resource_type}' not found. Define #{resource_type.singularize.classify}Resource < JSONAPI::Resource")
+      def initialize(resource_type, namespace: nil)
+        class_hint = build_class_hint(resource_type, namespace)
+        super("Resource class for '#{resource_type}' not found. Define #{class_hint} < JSONAPI::Resource")
+      end
+
+      private
+
+      def build_class_hint(resource_type, namespace)
+        base = "#{resource_type.singularize.classify}Resource"
+        namespace.present? ? "#{namespace.to_s.camelize}::#{base}" : base
       end
     end
 
-    def self.find(resource_type)
-      resource_class_name = "#{resource_type.singularize.classify}Resource"
-      resource_class_name.constantize
+    def self.find(resource_type, namespace: nil)
+      return find_namespaced(resource_type, namespace) if namespace.present?
+
+      find_flat(resource_type, namespace)
+    end
+
+    def self.find_namespaced(resource_type, namespace)
+      namespaced_class = build_resource_class_name(resource_type, namespace)
+      namespaced_class.constantize
     rescue NameError
-      raise MissingResourceClass, resource_type
+      raise MissingResourceClass.new(resource_type, namespace:) unless JSONAPI.configuration.namespace_fallback
+
+      find_flat(resource_type, namespace)
     end
 
-    def self.find_for_model(model_class)
-      # Handle ActiveStorage::Blob specially
-      return ActiveStorageBlobResource if defined?(::ActiveStorage) && model_class == ::ActiveStorage::Blob
+    def self.find_flat(resource_type, namespace)
+      flat_class = build_resource_class_name(resource_type, nil)
+      flat_class.constantize
+    rescue NameError
+      raise MissingResourceClass.new(resource_type, namespace:)
+    end
 
-      # For STI subclasses, try the specific subclass resource first
-      resource_type = model_class.name.underscore.pluralize
-      begin
-        find(resource_type)
-      rescue MissingResourceClass
-        # For STI subclasses, fall back to base class resource
-        raise unless model_class.respond_to?(:base_class) && model_class.base_class != model_class
+    def self.build_resource_class_name(resource_type, namespace)
+      base = "#{resource_type.singularize.classify}Resource"
+      return base unless namespace.present?
 
-        base_resource_type = model_class.base_class.name.underscore.pluralize
-        find(base_resource_type)
-      end
+      "#{namespace.to_s.camelize}::#{base}"
+    end
+
+    def self.find_for_model(model_class, namespace: nil)
+      return ActiveStorageBlobResource if active_storage_blob?(model_class)
+
+      find_resource_for_model(model_class, namespace)
+    end
+
+    def self.find_resource_for_model(model_class, namespace)
+      effective_namespace = namespace || extract_namespace_from_model(model_class)
+      resource_type = model_class.name.demodulize.underscore.pluralize
+
+      find(resource_type, namespace: effective_namespace)
+    rescue MissingResourceClass
+      find_base_class_resource(model_class, effective_namespace)
+    end
+
+    def self.find_base_class_resource(model_class, effective_namespace)
+      raise MissingResourceClass, model_class.name unless sti_subclass?(model_class)
+
+      base_resource_type = model_class.base_class.name.demodulize.underscore.pluralize
+      base_namespace = extract_namespace_from_model(model_class.base_class) || effective_namespace
+      find(base_resource_type, namespace: base_namespace)
+    end
+
+    def self.active_storage_blob?(model_class)
+      defined?(::ActiveStorage) && model_class == ::ActiveStorage::Blob
+    end
+
+    def self.sti_subclass?(model_class)
+      model_class.respond_to?(:base_class) && model_class.base_class != model_class
+    end
+
+    def self.extract_namespace_from_model(model_class)
+      parts = model_class.name.deconstantize
+      parts.presence&.underscore
     end
   end
 end

data/lib/json_api/routing.rb

@@ -4,32 +4,39 @@ module JSONAPI
   module Routing
     def jsonapi_resources(resource, controller: nil, defaults: {}, sti: false, **options, &)
       resource_name = resource.to_s
-      controller = detect_controller(resource_name) if controller.nil?
-
-      JSONAPI::ResourceLoader.find(resource_name)
-      defaults = defaults.merge(format: :jsonapi, resource_type: resource_name)
+      namespace = extract_namespace_from_scope
+      controller ||= detect_controller(resource_name, namespace)
+      defaults = build_jsonapi_defaults(defaults, resource_name, namespace)
       options[:only] = :index if sti
 
+      JSONAPI::ResourceLoader.find(resource_name, namespace:)
       define_resource_routes(resource, controller, defaults, options, &)
-      define_sti_routes(resource, resource_name, defaults, sti)
+      define_sti_routes(resource, resource_name, defaults, sti, namespace)
+    end
+
+    def build_jsonapi_defaults(defaults, resource_name, namespace)
+      defaults.merge(format: :jsonapi, resource_type: resource_name, jsonapi_namespace: namespace)
     end
 
     private
 
-    def detect_controller(resource_name)
-      potential_controller_name = build_controller_name(resource_name)
+    def extract_namespace_from_scope
+      @scope[:module]&.to_s.presence
+    end
+
+    def detect_controller(resource_name, namespace = nil)
+      potential_controller_name = build_controller_name(resource_name, namespace)
       potential_controller_name.constantize
       nil
     rescue NameError
       "json_api/resources"
     end
 
-    def build_controller_name(resource_name)
-      scoped_module = @scope[:module]
+    def build_controller_name(resource_name, namespace = nil)
       base_name = "#{resource_name.pluralize.camelize}Controller"
-      return base_name unless scoped_module
+      return base_name unless namespace
 
-      "#{scoped_module.to_s.camelize}::#{base_name}"
+      "#{namespace.to_s.camelize}::#{base_name}"
     end
 
     def define_resource_routes(resource, controller, defaults, options, &block)
@@ -47,15 +54,13 @@ module JSONAPI
       end
     end
 
-    def define_sti_routes(resource, resource_name, defaults, sti)
+    def define_sti_routes(resource, resource_name, defaults, sti, namespace = nil)
       return unless sti
 
       if sti.is_a?(Array)
-        define_explicit_sti_routes(sti,
-                                   defaults,)
+        define_explicit_sti_routes(sti, defaults)
       else
-        define_auto_sti_routes(resource, resource_name,
-                               defaults,)
+        define_auto_sti_routes(resource, resource_name, defaults, namespace)
       end
     end
 
@@ -63,13 +68,13 @@ module JSONAPI
       sti_resources.each { |sub_resource_name| jsonapi_resources(sub_resource_name, defaults:) }
     end
 
-    def define_auto_sti_routes(resource, resource_name, defaults)
-      resource_class = JSONAPI::ResourceLoader.find(resource_name)
+    def define_auto_sti_routes(resource, resource_name, defaults, namespace = nil)
+      resource_class = JSONAPI::ResourceLoader.find(resource_name, namespace:)
       model_class = resource_class.model_class
       return unless model_class.respond_to?(:descendants)
 
       model_class.descendants.each do |subclass|
-        sub_resource_name = subclass.name.underscore.pluralize.to_sym
+        sub_resource_name = subclass.name.demodulize.underscore.pluralize.to_sym
         next if sub_resource_name == resource.to_sym
 
         jsonapi_resources(sub_resource_name, defaults:)

data/lib/json_api/support/resource_identifier.rb

@@ -27,18 +27,35 @@ module JSONAPI
       raise ArgumentError, "Missing type or id in relationship data" unless type && id
 
       is_polymorphic = polymorphic_association?(definition, relationship_name)
-      validate_relationship_type!(type, association) unless is_polymorphic
+      validate_relationship_type!(type, association, definition) unless is_polymorphic
 
       find_related_record(type, id, association, is_polymorphic)
     end
 
-    def validate_relationship_type!(type, association)
-      expected_type = TypeConversion.model_type_name(association.klass)
-      return if type == expected_type
+    def validate_relationship_type!(type, association, definition = nil)
+      # Get expected type using the same format as the incoming type
+      format = resolve_type_format_from_incoming(type, definition)
+      expected_type = TypeConversion.model_type_name(association.klass, format:)
+
+      # Also check flat type for backwards compatibility
+      expected_flat = TypeConversion.model_type_name(association.klass, format: :flat)
+
+      return if type == expected_type || type == expected_flat
 
       raise ArgumentError, "Invalid relationship type: expected #{expected_type}, got #{type}"
     end
 
+    def resolve_type_format_from_incoming(type, definition)
+      # Detect format from incoming type string
+      if type.include?("/")
+        :prefixed
+      elsif definition.respond_to?(:type_format) && definition.type_format
+        definition.type_format
+      else
+        JSONAPI.configuration.namespace_type_format
+      end
+    end
+
     def find_related_record(type, id, association, is_polymorphic)
       related_model_class = resolve_related_model_class(type, association, is_polymorphic)
       related_model_class.find(id)

data/lib/json_api/support/type_conversion.rb

@@ -4,18 +4,52 @@ module JSONAPI
   module TypeConversion
     module_function
 
-    def type_to_class_name(type)
-      type.to_s.singularize.classify
+    def type_to_class_name(type, namespace: nil)
+      type_str = type.to_s
+      return prefixed_type_to_class(type_str) if type_str.include?("/")
+      return "#{namespace.to_s.camelize}::#{type_str.singularize.classify}" if namespace.present?
+
+      type_str.singularize.classify
+    end
+
+    def prefixed_type_to_class(type_str)
+      parts = type_str.split("/")
+      "#{parts[0..-2].join("/").camelize}::#{parts.last.singularize.classify}"
+    end
+
+    def model_type_name(model_class, format: nil)
+      format ||= JSONAPI.configuration.namespace_type_format
+
+      full_name = model_class.name.underscore.pluralize
+
+      format_type_name(full_name, format)
+    end
+
+    def resource_type_name(definition_class, format: nil)
+      format ||= resolve_type_format(definition_class)
+
+      full_name = definition_class.name.sub(/Resource$/, "").underscore.pluralize
+
+      format_type_name(full_name, format)
     end
 
-    def model_type_name(model_class)
-      model_class.name.underscore.pluralize
+    def format_type_name(full_name, format)
+      case format
+      when :prefixed
+        full_name
+      when :underscore
+        full_name.tr("/", "_")
+      else # :flat
+        full_name.split("/").last
+      end
     end
 
-    def resource_type_name(definition_class)
-      type_name = definition_class.name.sub(/Resource$/, "").underscore.pluralize
-      # Remove namespace prefix if present (e.g., "json_api/active_storage_blobs" -> "active_storage_blobs")
-      type_name.split("/").last
+    def resolve_type_format(definition_class)
+      if definition_class.respond_to?(:type_format) && definition_class.type_format
+        definition_class.type_format
+      else
+        JSONAPI.configuration.namespace_type_format
+      end
     end
   end
 end

data/lib/json_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONAPI
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Emil Kampp
@@ -90,13 +90,6 @@ files:
 - lib/json_api/controllers/concerns/relationships/serialization.rb
 - lib/json_api/controllers/concerns/relationships/sorting.rb
 - lib/json_api/controllers/concerns/relationships/updating.rb
-- lib/json_api/controllers/concerns/relationships_controller/active_storage_removal.rb
-- lib/json_api/controllers/concerns/relationships_controller/events.rb
-- lib/json_api/controllers/concerns/relationships_controller/removal.rb
-- lib/json_api/controllers/concerns/relationships_controller/response_helpers.rb
-- lib/json_api/controllers/concerns/relationships_controller/serialization.rb
-- lib/json_api/controllers/concerns/relationships_controller/sorting.rb
-- lib/json_api/controllers/concerns/relationships_controller/updating.rb
 - lib/json_api/controllers/concerns/resource_actions.rb
 - lib/json_api/controllers/concerns/resource_actions/crud_helpers.rb
 - lib/json_api/controllers/concerns/resource_actions/field_validation.rb

data/lib/json_api/controllers/concerns/relationships_controller/active_storage_removal.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-module JSONAPI
-  module RelationshipsController
-    module ActiveStorageRemoval
-      extend ActiveSupport::Concern
-
-      private
-
-      def remove_active_storage_relationship(relationship_data)
-        reflection = @resource.class.reflect_on_attachment(@relationship_name)
-        if reflection&.macro == :has_many_attached
-          remove_many_active_storage_attachments(relationship_data)
-        else
-          remove_one_active_storage_attachment(relationship_data)
-        end
-      end
-
-      def remove_many_active_storage_attachments(relationship_data)
-        raise ArgumentError, "Expected array for to-many relationship removal" unless relationship_data.is_a?(Array)
-        return if relationship_data.empty?
-
-        attachment_proxy = @resource.public_send(@relationship_name)
-        return unless attachment_proxy.attached?
-
-        blob_ids = extract_blob_ids(relationship_data)
-        attachments = attachment_proxy.attachments.where(blob_id: blob_ids)
-        attachments.each(&:purge)
-      end
-
-      def remove_one_active_storage_attachment(relationship_data)
-        validate_single_removal_identifier!(relationship_data)
-        return if relationship_data.nil?
-
-        attachment_proxy = @resource.public_send(@relationship_name)
-        return unless attachment_proxy.attached?
-
-        blob_id = extract_single_blob_id(relationship_data)
-        attachment = attachment_proxy.attachments.find_by(blob_id:)
-        attachment&.purge
-      end
-
-      def extract_blob_ids(relationship_data)
-        relationship_data.map do |identifier|
-          extract_blob_id_from_identifier(identifier)
-        end
-      end
-
-      def extract_single_blob_id(relationship_data)
-        extract_blob_id_from_identifier(relationship_data)
-      end
-
-      def extract_blob_id_from_identifier(identifier)
-        type = RelationshipHelpers.extract_type_from_identifier(identifier)
-        id = RelationshipHelpers.extract_id_from_identifier(identifier)
-        validate_blob_type!(type)
-        id.to_i
-      end
-
-      def validate_blob_type!(type)
-        return if self.class.active_storage_blob_type?(type)
-
-        raise ArgumentError, "Expected active_storage_blobs type, got #{type}"
-      end
-    end
-  end
-end

data/lib/json_api/controllers/concerns/relationships_controller/events.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-module JSONAPI
-  module RelationshipsController
-    module Events
-      extend ActiveSupport::Concern
-
-      private
-
-      def emit_relationship_event(action, relationship_data)
-        resource_type_name = params[:resource_type] || @resource_name.pluralize
-
-        JSONAPI::Instrumentation.relationship_event(
-          action:,
-          resource_type: resource_type_name,
-          resource_id: @resource.id,
-          relationship_name: @relationship_name.to_s,
-          related_ids: extract_related_ids(relationship_data),
-          related_type: extract_related_type(relationship_data),
-        )
-      end
-
-      def extract_related_ids(relationship_data)
-        return nil if relationship_data.nil?
-
-        if relationship_data.is_a?(Array)
-          relationship_data.filter_map { |item| item[:id] }
-        else
-          [relationship_data[:id]].compact
-        end
-      end
-
-      def extract_related_type(relationship_data)
-        return nil if relationship_data.nil?
-
-        if relationship_data.is_a?(Array)
-          relationship_data.first&.dig(:type)
-        else
-          relationship_data[:type]
-        end
-      end
-    end
-  end
-end

data/lib/json_api/controllers/concerns/relationships_controller/removal.rb

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "active_storage_removal"
-
-module JSONAPI
-  module RelationshipsController
-    module Removal
-      extend ActiveSupport::Concern
-      include ActiveStorageRemoval
-
-      private
-
-      def remove_relationship(relationship_data)
-        if active_storage_attachment?(@relationship_name, @resource.class)
-          return remove_active_storage_relationship(relationship_data)
-        end
-
-        remove_association_relationship(relationship_data)
-      rescue ActiveRecord::NotNullViolation, ActiveRecord::RecordInvalid => e
-        raise ArgumentError, "Cannot remove relationship: #{e.message}"
-      end
-
-      def remove_association_relationship(relationship_data)
-        association = @resource.class.reflect_on_association(@relationship_name)
-        raise ArgumentError, "Association not found: #{@relationship_name}" unless association
-
-        ensure_relationship_writable!(association)
-        dispatch_relationship_removal(association, relationship_data)
-      end
-
-      def dispatch_relationship_removal(association, relationship_data)
-        if association.collection?
-          remove_from_many_relationship(association, relationship_data)
-        else
-          remove_from_one_relationship(association, relationship_data)
-        end
-      end
-
-      def remove_from_many_relationship(association, relationship_data)
-        raise ArgumentError, "Expected array for to-many relationship removal" unless relationship_data.is_a?(Array)
-        return if relationship_data.empty?
-
-        remove_from_collection(association, relationship_data)
-      end
-
-      def remove_from_collection(association, relationship_data)
-        collection_ids = @resource.public_send(@relationship_name).pluck(:id)
-        foreign_key = association.foreign_key
-
-        ActiveRecord::Base.transaction do
-          relationship_data.each do |identifier|
-            remove_resource_from_collection(identifier, association, collection_ids, foreign_key)
-          end
-        end
-      end
-
-      def remove_resource_from_collection(identifier, association, collection_ids, foreign_key)
-        resource = RelationshipHelpers.resolve_and_find_related_resource(
-          identifier,
-          association:,
-          resource_class: @resource_class,
-          relationship_name: @relationship_name,
-        )
-        return unless collection_ids.include?(resource.id)
-
-        resource.update!(foreign_key => nil)
-      end
-
-      def remove_from_one_relationship(association, relationship_data)
-        validate_single_removal_identifier!(relationship_data)
-        return if relationship_data.nil?
-
-        remove_single_association(association, relationship_data)
-      end
-
-      def validate_single_removal_identifier!(relationship_data)
-        return unless relationship_data.is_a?(Array)
-
-        raise ArgumentError, "Expected single resource identifier for to-one relationship"
-      end
-
-      def remove_single_association(association, relationship_data)
-        related_resource = find_related_resource(relationship_data, association)
-        current_resource = @resource.public_send(@relationship_name)
-        return unless current_resource == related_resource
-
-        @resource.public_send("#{@relationship_name}=", nil)
-        @resource.save!
-      end
-    end
-  end
-end

data/lib/json_api/controllers/concerns/relationships_controller/response_helpers.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module JSONAPI
-  module RelationshipsController
-    module ResponseHelpers
-      extend ActiveSupport::Concern
-
-      private
-
-      def build_show_response
-        response_data = { data: serialize_relationship_data, links: serialize_relationship_links }
-        meta = serialize_relationship_meta
-        response_data[:meta] = meta if meta.present?
-        response_data
-      end
-
-      def save_and_render_relationship(relationship_data)
-        if @resource.save
-          emit_relationship_event(:updated, relationship_data)
-          render_relationship_response
-        else
-          render_validation_errors(@resource)
-        end
-      end
-
-      def render_relationship_response
-        render json: {
-          data: serialize_relationship_data,
-          links: serialize_relationship_links,
-          meta: serialize_relationship_meta,
-        }.compact, status: :ok
-      end
-
-      def finalize_relationship_removal(relationship_data)
-        association = @resource.class.reflect_on_association(@relationship_name)
-        return emit_and_respond_no_content(relationship_data) unless association && !association.collection?
-
-        save_to_one_removal(relationship_data)
-      end
-
-      def save_to_one_removal(relationship_data)
-        if @resource.save
-          emit_and_respond_no_content(relationship_data)
-        else
-          render_validation_errors(@resource)
-        end
-      end
-
-      def emit_and_respond_no_content(relationship_data)
-        emit_relationship_event(:removed, relationship_data)
-        head :no_content
-      end
-    end
-  end
-end

data/lib/json_api/controllers/concerns/relationships_controller/serialization.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-module JSONAPI
-  module RelationshipsController
-    module Serialization
-      extend ActiveSupport::Concern
-
-      private
-
-      def serialize_relationship_data
-        association = @resource.class.reflect_on_association(@relationship_name)
-        return nil unless association
-
-        related = fetch_related_data(association)
-        serialize_related(related, association)
-      end
-
-      def fetch_related_data(association)
-        related = @resource.public_send(@relationship_name)
-        return related unless association.collection? && related.respond_to?(:order)
-
-        apply_sorting_to_relationship(related, association)
-      end
-
-      def serialize_related(related, association)
-        return serialize_collection_relationship(related, association) if association.collection?
-
-        serialize_single_relationship(related, association) if related
-      end
-
-      def serialize_collection_relationship(related, association)
-        return [] if related.nil?
-
-        related.map { |r| serialize_resource_identifier(r, association) }
-      end
-
-      def serialize_single_relationship(related, association)
-        serialize_resource_identifier(related, association)
-      end
-
-      def serialize_resource_identifier(resource_instance, association)
-        RelationshipHelpers.serialize_resource_identifier(
-          resource_instance,
-          association:,
-          resource_class: @resource_class,
-        )
-      end
-
-      def serialize_relationship_links
-        {
-          self: relationship_self_url,
-          related: relationship_related_url,
-        }
-      end
-
-      def relationship_self_url
-        "/#{params[:resource_type]}/#{params[:id]}/relationships/#{params[:relationship_name]}"
-      end
-
-      def relationship_related_url
-        "/#{params[:resource_type]}/#{params[:id]}/#{params[:relationship_name]}"
-      end
-
-      def serialize_relationship_meta
-        relationship_def = find_relationship_definition
-        return nil unless relationship_def
-
-        relationship_def[:meta]
-      end
-    end
-  end
-end

data/lib/json_api/controllers/concerns/relationships_controller/sorting.rb

@@ -1,114 +0,0 @@
-# frozen_string_literal: true
-
-module JSONAPI
-  module RelationshipsController
-    module Sorting
-      extend ActiveSupport::Concern
-
-      private
-
-      def apply_sorting_to_relationship(related, association)
-        sorts = parse_sort_param
-        return related if sorts.empty?
-
-        related_model = association.klass
-        db_sorts, virtual_sorts = partition_sorts_by_type(sorts, related_model)
-
-        related = apply_db_sorts(related, db_sorts)
-        apply_virtual_sorts_if_needed(related, virtual_sorts, related_model)
-      end
-
-      def partition_sorts_by_type(sorts, related_model)
-        sorts.partition do |sort_field|
-          field = RelationshipHelpers.extract_sort_field_name(sort_field)
-          related_model.column_names.include?(field.to_s)
-        end
-      end
-
-      def apply_db_sorts(related, db_sorts)
-        db_sorts.each do |sort_field|
-          direction = RelationshipHelpers.extract_sort_direction(sort_field)
-          field = RelationshipHelpers.extract_sort_field_name(sort_field)
-          related = related.order(field => direction)
-        end
-        related
-      end
-
-      def apply_virtual_sorts_if_needed(related, virtual_sorts, related_model)
-        return related unless virtual_sorts.any?
-
-        resource_class = ResourceLoader.find_for_model(related_model)
-        sort_records_by_virtual_attributes(related.to_a, virtual_sorts, resource_class)
-      end
-
-      def sort_records_by_virtual_attributes(records, virtual_sorts, resource_class)
-        records.sort do |a, b|
-          compare_records(a, b, virtual_sorts, resource_class)
-        end
-      end
-
-      def compare_records(record_a, record_b, virtual_sorts, resource_class)
-        virtual_sorts.each do |sort_field|
-          comparison = compare_by_field(record_a, record_b, sort_field, resource_class)
-          return comparison unless comparison.zero?
-        end
-        0
-      end
-
-      def compare_by_field(record_a, record_b, sort_field, resource_class)
-        direction = RelationshipHelpers.extract_sort_direction(sort_field)
-        field = RelationshipHelpers.extract_sort_field_name(sort_field)
-
-        value_a = get_virtual_value(record_a, field, resource_class)
-        value_b = get_virtual_value(record_b, field, resource_class)
-
-        comparison = compare_values(value_a, value_b)
-        direction == :desc ? -comparison : comparison
-      end
-
-      def get_virtual_value(record, field, resource_class)
-        resource_instance = resource_class.new(record, {})
-        field_sym = field.to_sym
-        return resource_instance.public_send(field_sym) if resource_instance.respond_to?(field_sym, false)
-
-        nil
-      end
-
-      def compare_values(value_a, value_b)
-        return 0 if value_a.nil? && value_b.nil?
-        return -1 if value_a.nil?
-        return 1 if value_b.nil?
-
-        value_a <=> value_b
-      end
-
-      def validate_sort_param
-        sorts = parse_sort_param
-        return if sorts.empty?
-
-        association = @resource.class.reflect_on_association(@relationship_name)
-        return unless association&.collection?
-
-        validate_sort_fields_for_association(sorts, association)
-      end
-
-      def validate_sort_fields_for_association(sorts, association)
-        resource_class = ResourceLoader.find_for_model(association.klass)
-        valid_fields = valid_sort_fields_for_resource(resource_class, association.klass)
-        invalid_fields = invalid_sort_fields_for_columns(sorts, valid_fields)
-        return if invalid_fields.empty?
-
-        render_invalid_sort_fields(invalid_fields)
-      end
-
-      def render_invalid_sort_fields(invalid_fields)
-        render_parameter_errors(
-          invalid_fields,
-          title: "Invalid Sort Field",
-          detail_proc: ->(field) { "Invalid sort field requested: #{field}" },
-          source_proc: ->(_field) { { parameter: "sort" } },
-        )
-      end
-    end
-  end
-end

data/lib/json_api/controllers/concerns/relationships_controller/updating.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-module JSONAPI
-  module RelationshipsController
-    module Updating
-      extend ActiveSupport::Concern
-
-      private
-
-      def update_relationship(relationship_data)
-        association = @resource.class.reflect_on_association(@relationship_name)
-        raise ArgumentError, "Association not found: #{@relationship_name}" unless association
-
-        ensure_relationship_writable!(association)
-        apply_relationship_update(association, relationship_data)
-      end
-
-      def apply_relationship_update(association, relationship_data)
-        if association.collection?
-          update_to_many_relationship(association, relationship_data)
-        else
-          update_to_one_relationship(association, relationship_data)
-        end
-      end
-
-      def update_to_many_relationship(association, relationship_data)
-        if relationship_data.nil? || empty_array?(relationship_data)
-          @resource.public_send("#{@relationship_name}=", [])
-          return
-        end
-
-        raise ArgumentError, "Expected array for to-many relationship" unless relationship_data.is_a?(Array)
-
-        related_resources = resolve_related_resources(relationship_data, association)
-        @resource.public_send("#{@relationship_name}=", related_resources)
-      end
-
-      def empty_array?(data)
-        data.is_a?(Array) && data.empty?
-      end
-
-      def resolve_related_resources(relationship_data, association)
-        relationship_data.map { |identifier| find_related_resource(identifier, association) }
-      end
-
-      def update_to_one_relationship(association, relationship_data)
-        if relationship_data.nil?
-          @resource.public_send("#{@relationship_name}=", nil)
-          return
-        end
-
-        validate_single_identifier!(relationship_data)
-        related_resource = find_related_resource(relationship_data, association)
-        @resource.public_send("#{@relationship_name}=", related_resource)
-      end
-
-      def validate_single_identifier!(relationship_data)
-        return unless relationship_data.is_a?(Array)
-
-        raise ArgumentError, "Expected single resource identifier for to-one relationship"
-      end
-
-      def find_related_resource(identifier, association)
-        RelationshipHelpers.resolve_and_find_related_resource(
-          identifier,
-          association:,
-          resource_class: @resource_class,
-          relationship_name: @relationship_name,
-        )
-      end
-    end
-  end
-end