jpie 0.4.4 → 1.0.0

data/lib/json_api/resources/resource.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  class Resource
+    class << self
+      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)
+      rescue NameError
+        nil
+      end
+
+      def attributes(*attrs)
+        @attributes ||= []
+        @attributes.concat(attrs.map(&:to_sym))
+        @attributes.uniq!
+      end
+
+      def creatable_fields(*fields)
+        @creatable_fields ||= []
+        @creatable_fields.concat(fields.map(&:to_sym))
+        @creatable_fields.uniq!
+      end
+
+      def updatable_fields(*fields)
+        @updatable_fields ||= []
+        @updatable_fields.concat(fields.map(&:to_sym))
+        @updatable_fields.uniq!
+      end
+
+      def filters(*filter_names)
+        @filters ||= []
+        @filters.concat(filter_names.map(&:to_sym))
+        @filters.uniq!
+      end
+
+      def permitted_filters_through
+        relationship_names
+      end
+
+      def sortable_fields(*field_names)
+        @sortable_fields ||= []
+        @sortable_fields.concat(field_names.map(&:to_sym))
+        @sortable_fields.uniq!
+      end
+
+      def meta(hash = nil, &block)
+        @meta = hash || block
+      end
+
+      def resource_meta
+        if instance_variable_defined?(:@meta)
+          @meta
+        elsif superclass != JSONAPI::Resource && superclass.respond_to?(:resource_meta)
+          superclass.resource_meta
+        end
+      end
+
+      def has_one(name, meta: nil, **options)
+        @relationships ||= []
+
+        unless options.key?(:polymorphic)
+          model_klass = reflection_model_class
+          if model_klass.respond_to?(:reflect_on_association)
+            reflection = model_klass.reflect_on_association(name)
+            options[:polymorphic] = reflection&.polymorphic?
+          end
+        end
+
+        @relationships << { name: name.to_sym, type: :has_one, meta:, options: }
+      end
+
+      def has_many(name, meta: nil, **options)
+        @relationships ||= []
+
+        if options[:append_only] && options[:purge_on_nil] == true
+          raise ArgumentError, "Cannot use append_only: true with purge_on_nil: true"
+        end
+
+        options[:purge_on_nil] = false if options[:append_only] && !options.key?(:purge_on_nil)
+
+        unless options.key?(:polymorphic)
+          model_klass = reflection_model_class
+          if model_klass.respond_to?(:reflect_on_association)
+            reflection = model_klass.reflect_on_association(name)
+            options[:polymorphic] = reflection&.polymorphic?
+          end
+        end
+
+        @relationships << { name: name.to_sym, type: :has_many, meta:, options: }
+      end
+
+      def belongs_to(name, meta: nil, **options)
+        @relationships ||= []
+
+        unless options.key?(:polymorphic)
+          model_klass = reflection_model_class
+          if model_klass.respond_to?(:reflect_on_association)
+            reflection = model_klass.reflect_on_association(name)
+            options[:polymorphic] = reflection&.polymorphic?
+          end
+        end
+
+        @relationships << { name: name.to_sym, type: :belongs_to, meta:, options: }
+      end
+
+      def permitted_attributes
+        # For STI subclasses, merge with parent class attributes unless the subclass declares its own
+        declared_attributes = instance_variable_defined?(:@attributes)
+        attrs = @attributes || []
+        if !declared_attributes &&
+           superclass != JSONAPI::Resource &&
+           superclass.respond_to?(:permitted_attributes)
+          attrs = superclass.permitted_attributes + attrs
+        end
+        attrs.uniq
+      end
+
+      def permitted_creatable_fields
+        if instance_variable_defined?(:@creatable_fields)
+          fields = @creatable_fields || []
+        elsif superclass != JSONAPI::Resource &&
+              superclass.respond_to?(:permitted_creatable_fields) &&
+              superclass.instance_variable_defined?(:@creatable_fields)
+          parent_fields = superclass.permitted_creatable_fields
+          fields = parent_fields
+        else
+          fields = permitted_attributes
+        end
+
+        fields.uniq
+      end
+
+      def permitted_updatable_fields
+        if instance_variable_defined?(:@updatable_fields)
+          fields = @updatable_fields || []
+        elsif superclass != JSONAPI::Resource &&
+              superclass.respond_to?(:permitted_updatable_fields) &&
+              superclass.instance_variable_defined?(:@updatable_fields)
+          parent_fields = superclass.permitted_updatable_fields
+          fields = parent_fields
+        else
+          fields = permitted_attributes
+        end
+
+        fields.uniq
+      end
+
+      def permitted_filters
+        # For STI subclasses, merge with parent class filters unless the subclass declares its own
+        declared_filters = instance_variable_defined?(:@filters)
+        filter_list = @filters || []
+        if !declared_filters &&
+           superclass != JSONAPI::Resource &&
+           superclass.respond_to?(:permitted_filters)
+          filter_list = superclass.permitted_filters + filter_list
+        end
+        filter_list.uniq
+      end
+
+      def permitted_sortable_fields
+        # Include both attributes (which are sortable) and sort-only fields
+        # For STI subclasses, merge with parent class sortable fields when no subclass DSL is declared
+        declared_sortable = instance_variable_defined?(:@sortable_fields)
+        declared_attributes = instance_variable_defined?(:@attributes)
+        sort_fields = @sortable_fields || []
+        if !declared_sortable &&
+           !declared_attributes &&
+           superclass != JSONAPI::Resource &&
+           superclass.respond_to?(:permitted_sortable_fields)
+          parent_sort_fields = superclass.permitted_sortable_fields
+          # Only merge parent's sort-only fields, not attributes (attributes are already included via permitted_attributes)
+          parent_attributes = superclass.permitted_attributes
+          parent_sort_only = parent_sort_fields - parent_attributes
+          sort_fields = parent_sort_only + sort_fields
+        end
+        # Combine with attributes (all attributes are sortable)
+        (permitted_attributes + sort_fields).uniq
+      end
+
+      def relationship_definitions
+        # For STI subclasses, merge with parent class relationships
+        declared_relationships = instance_variable_defined?(:@relationships)
+        rels = @relationships || []
+        if !declared_relationships &&
+           superclass != JSONAPI::Resource &&
+           superclass.respond_to?(:relationship_definitions)
+          rels = superclass.relationship_definitions + rels
+        end
+        rels.uniq { |r| r[:name] }
+      end
+
+      def relationship_names
+        relationship_definitions.map { |r| r[:name] }
+      end
+
+      def model_class
+        name.sub(/Resource$/, "").classify.constantize
+      end
+
+      def safe_model_class
+        return nil unless respond_to?(:name) && name
+        return nil unless defined?(ActiveSupport)
+
+        name.sub(/Resource$/, "").classify.safe_constantize
+      rescue NoMethodError
+        nil
+      end
+
+      def reflection_model_class
+        model_class
+      rescue NameError
+        safe_model_class
+      rescue StandardError
+        safe_model_class
+      end
+    end
+
+    # Instance method to initialize resource with model instance
+    # This allows the serializer to instantiate resources directly
+    def initialize(record = nil, context = {})
+      @record = record
+      @context = context
+      @transformed_params = {}
+    end
+
+    # Accessor for the underlying model instance
+    # @record is the preferred internal name, but :resource is kept for backward compatibility
+    attr_reader :record
+    alias resource record
+
+    # Returns transformed params accumulated by resource setters during deserialization
+    # Resources can override this method or use the default implementation
+    def transformed_params
+      @transformed_params || {}
+    end
+  end
+end

data/lib/json_api/resources/resource_loader.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+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")
+      end
+    end
+
+    def self.find(resource_type)
+      resource_class_name = "#{resource_type.singularize.classify}Resource"
+      resource_class_name.constantize
+    rescue NameError
+      raise MissingResourceClass, resource_type
+    end
+
+    def self.find_for_model(model_class)
+      # Handle ActiveStorage::Blob specially
+      return ActiveStorageBlobResource if defined?(::ActiveStorage) && model_class == ::ActiveStorage::Blob
+
+      # 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
+
+        base_resource_type = model_class.base_class.name.underscore.pluralize
+        find(base_resource_type)
+      end
+    end
+  end
+end

data/lib/json_api/routing.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Routing
+    def jsonapi_resources(resource, controller: nil, defaults: {}, sti: false, **options, &block)
+      resource_name = resource.to_s
+
+      # Smart Controller Detection:
+      # If no controller is specified, try to find one in the current scope.
+      # If we find "Trust::VendorsController", use it (by passing nil to 'resources').
+      # If NOT found, default to the generic "json_api/resources".
+      if controller.nil?
+        scoped_module = @scope[:module]
+        potential_controller_name = if scoped_module
+                                      "#{scoped_module.to_s.camelize}::#{resource_name.pluralize.camelize}Controller"
+                                    else
+                                      "#{resource_name.pluralize.camelize}Controller"
+                                    end
+
+        begin
+          # Check if the controller exists constant
+          potential_controller_name.constantize
+          # It exists! Leave controller as nil so Rails uses standard routing conventions
+        rescue NameError
+          # It doesn't exist, fallback to generic controller
+          controller = "json_api/resources"
+        end
+      end
+
+      # Validate that resource class exists at boot time
+      JSONAPI::ResourceLoader.find(resource_name)
+
+      defaults = defaults.merge(format: :jsonapi, resource_type: resource_name)
+
+      options[:only] = :index if sti
+
+      resources(resource, controller:, defaults:, **options) do
+        member do
+          get "relationships/:relationship_name", to: "json_api/relationships#show", as: :relationship
+          patch "relationships/:relationship_name", to: "json_api/relationships#update"
+          delete "relationships/:relationship_name", to: "json_api/relationships#destroy"
+        end
+
+        instance_eval(&block) if block
+      end
+
+      return unless sti
+
+      if sti.is_a?(Array)
+        sti.each do |sub_resource_name|
+          jsonapi_resources(sub_resource_name, defaults:)
+        end
+      else
+        begin
+          resource_class = JSONAPI::ResourceLoader.find(resource_name)
+          model_class = resource_class.model_class
+
+          if model_class.respond_to?(:descendants)
+            model_class.descendants.each do |subclass|
+              sub_resource_name = subclass.name.underscore.pluralize.to_sym
+              next if sub_resource_name == resource.to_sym
+
+              jsonapi_resources(sub_resource_name, defaults:)
+            end
+          end
+        rescue NameError, JSONAPI::ResourceLoader::MissingResourceClass
+          # Silently skip if model/resource not found
+        end
+      end
+    end
+  end
+end

data/lib/json_api/serialization/deserializer.rb

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+require "json_api/support/relationship_guard"
+
+module JSONAPI
+  class Deserializer
+    include ActiveStorageSupport
+
+    def initialize(params, model_class:, action: :create)
+      @params = ParamHelpers.deep_symbolize_params(params)
+      @model_class = model_class
+      @definition = ResourceLoader.find_for_model(model_class)
+      @action = action.to_sym
+    end
+
+    def attributes
+      attrs = extract_attributes_from_params
+      attrs = attrs.transform_keys(&:to_sym) if attrs.respond_to?(:transform_keys)
+      permitted_attrs = permitted_attributes_for_action
+      attrs.slice(*permitted_attrs)
+    end
+
+    def extract_attributes_from_params
+      @params.dig(:data, :attributes) || @params[:attributes] || {}
+    end
+
+    def permitted_attributes_for_action
+      fields = if @action == :create
+                 @definition.permitted_creatable_fields
+               else
+                 @definition.permitted_updatable_fields
+               end
+      fields.map(&:to_sym)
+    end
+
+    def relationships
+      # Handle both nested (:data => {:relationships => ...}) and flat (:relationships => ...) structures
+      rels = @params.dig(:data, :relationships) || @params[:relationships] || {}
+      rels = rels.to_h if rels.respond_to?(:to_h)
+      rels.is_a?(Hash) ? rels : {}
+    end
+
+    def relationship_ids(relationship_name)
+      relationship = find_relationship(relationship_name)
+      return [] unless relationship
+
+      data = extract_relationship_data(relationship)
+      return [] unless data
+
+      extract_ids_from_data(data)
+    end
+
+    def find_relationship(relationship_name)
+      relationships[relationship_name.to_sym]
+    end
+
+    def extract_relationship_data(relationship)
+      relationship[:data]
+    end
+
+    def extract_ids_from_data(data)
+      if data.is_a?(Array)
+        data.map { |r| extract_id_from_identifier(r) }
+      else
+        [extract_id_from_identifier(data)]
+      end
+    end
+
+    def extract_id_from_identifier(identifier)
+      RelationshipHelpers.extract_id_from_identifier(identifier)
+    end
+
+    def relationship_id(relationship_name)
+      relationship_ids(relationship_name).first
+    end
+
+    def to_model_attributes
+      attrs = attributes.dup
+      attrs = apply_virtual_attribute_transformers(attrs)
+      attrs = process_relationships(attrs)
+      attrs.transform_keys(&:to_s)
+    end
+
+    def apply_virtual_attribute_transformers(attrs)
+      transformed_params, attributes_with_setters = invoke_setter_methods(attrs)
+      attributes_with_setters.each { |attr_sym| attrs.delete(attr_sym) }
+      merge_transformed_params(attrs, transformed_params)
+      attrs
+    end
+
+    def merge_transformed_params(attrs, transformed_params)
+      return attrs unless transformed_params.is_a?(Hash) && transformed_params.any?
+
+      transformed_params_symbolized = transformed_params.transform_keys(&:to_sym)
+      attrs.merge!(transformed_params_symbolized)
+      attrs
+    end
+
+    def process_relationships(attrs)
+      permitted_relationships = @definition.relationship_names.map(&:to_s)
+
+      relationships.each do |key, value|
+        association_name = key.to_s
+        next unless permitted_relationships.include?(association_name)
+
+        process_relationship(attrs, association_name, value)
+      end
+
+      attrs
+    end
+
+    def invoke_setter_methods(attrs)
+      definition_instance = create_definition_instance_for_setters
+      return [{}, []] unless definition_instance.respond_to?(:transformed_params, true)
+
+      attributes_with_setters = call_setters(attrs, definition_instance)
+      [definition_instance.transformed_params, attributes_with_setters]
+    end
+
+    def create_definition_instance_for_setters
+      @definition.new(nil, {})
+    end
+
+    def call_setters(attrs, definition_instance)
+      attributes_with_setters = []
+      attrs.each do |attr_sym, attr_value|
+        next unless has_setter?(definition_instance, attr_sym)
+
+        definition_instance.public_send(:"#{attr_sym}=", attr_value)
+        attributes_with_setters << attr_sym
+      end
+      attributes_with_setters
+    end
+
+    def has_setter?(definition_instance, attr_sym)
+      definition_instance.respond_to?(:"#{attr_sym}=", false)
+    end
+
+    def process_relationship(attrs, association_name, value)
+      value_hash = normalize_relationship_value(value)
+      data = extract_data_from_value(value_hash)
+      param_name = association_param_name(association_name)
+
+      ensure_relationship_writable!(association_name)
+
+      return handle_null_relationship(attrs, param_name, association_name) if data.nil?
+      return handle_empty_array_relationship(attrs, param_name, association_name) if empty_array?(data)
+
+      validate_relationship_data_format!(data, association_name)
+      process_relationship_data(attrs, association_name, param_name, data)
+    end
+
+    def normalize_relationship_value(value)
+      value.is_a?(Hash) ? value : value.to_h
+    end
+
+    def extract_data_from_value(value_hash)
+      value_hash[:data]
+    end
+
+    def empty_array?(data)
+      data.is_a?(Array) && data.empty?
+    end
+
+    def handle_null_relationship(attrs, param_name, association_name)
+      # Handle ActiveStorage attachments specially
+      if active_storage_attachment?(association_name)
+        attrs[association_name.to_s] = nil
+      else
+        attrs["#{param_name}_id"] = nil
+        attrs["#{param_name}_type"] = nil if polymorphic_association?(association_name)
+      end
+    end
+
+    def handle_empty_array_relationship(attrs, param_name, association_name)
+      # Check if this is an ActiveStorage attachment
+      if active_storage_attachment?(association_name)
+        attrs[association_name.to_s] = []
+      else
+        attrs["#{param_name.singularize}_ids"] = []
+      end
+    end
+
+    def validate_relationship_data_format!(data, association_name)
+      return if valid_relationship_data?(data)
+
+      raise ArgumentError, "Invalid relationship data for #{association_name}: missing type or id"
+    end
+
+    def process_relationship_data(attrs, association_name, param_name, data)
+      if data.is_a?(Array)
+        process_to_many_relationship(attrs, association_name, param_name, data)
+      else
+        process_to_one_relationship(attrs, association_name, param_name, data)
+      end
+    end
+
+    def process_to_many_relationship(attrs, association_name, param_name, data)
+      ids = data.map { |r| extract_id(r) }
+      types = data.map { |r| extract_type(r) }
+
+      # Check if this is an ActiveStorage attachment
+      if types.any? && self.class.active_storage_blob_type?(types.first)
+        process_active_storage_attachment(attrs, association_name, ids, singular: false)
+        return
+      end
+
+      validate_relationship_type(association_name, types.first) unless polymorphic_association?(association_name)
+      attrs["#{param_name.singularize}_ids"] = ids
+    end
+
+    def process_to_one_relationship(attrs, association_name, param_name, data)
+      id = extract_id(data)
+      type = extract_type(data)
+
+      if self.class.active_storage_blob_type?(type)
+        return process_active_storage_attachment(attrs, association_name, id, singular: true)
+      end
+
+      process_regular_to_one_relationship(attrs, association_name, param_name, id, type)
+    end
+
+    def process_regular_to_one_relationship(attrs, association_name, param_name, id, type)
+      if polymorphic_association?(association_name)
+        process_polymorphic_relationship(attrs, association_name, param_name, id, type)
+      else
+        process_non_polymorphic_relationship(attrs, association_name, param_name, id, type)
+      end
+    end
+
+    def process_polymorphic_relationship(attrs, association_name, param_name, id, type)
+      class_name = validate_and_get_class_name(type, association_name)
+      attrs["#{param_name}_id"] = id
+      attrs["#{param_name}_type"] = class_name
+    end
+
+    def validate_and_get_class_name(type, association_name)
+      class_name = RelationshipHelpers.type_to_class_name(type)
+      class_name.constantize
+      class_name
+    rescue NameError
+      raise ArgumentError,
+            "Invalid relationship type for #{association_name}: " \
+            "'#{type}' does not correspond to a valid model class"
+    end
+
+    def process_non_polymorphic_relationship(attrs, association_name, param_name, id, type)
+      validate_relationship_type(association_name, type)
+      attrs["#{param_name}_id"] = id
+    end
+
+    private
+
+    def association_param_name(association_name)
+      return association_name.singularize unless @model_class
+
+      association = @model_class.reflect_on_association(association_name.to_sym)
+      # If association doesn't exist, return the singularized name as fallback
+      return association_name.singularize unless association
+
+      # Use the actual association name (which is already singular for belongs_to, singular for has_many)
+      association.name.to_s
+    end
+
+    def polymorphic_association?(association_name)
+      RelationshipHelpers.polymorphic_association?(@definition, association_name)
+    end
+
+    def validate_relationship_type(association_name, type)
+      relationship_def = find_relationship_definition(association_name)
+      return unless relationship_def
+
+      association = @model_class.reflect_on_association(association_name.to_sym)
+      return unless association
+
+      if relationship_def[:options][:polymorphic]
+        validate_polymorphic_type(association_name, type)
+      else
+        validate_non_polymorphic_type(association_name, type, association)
+      end
+    end
+
+    def find_relationship_definition(association_name)
+      RelationshipHelpers.find_relationship_definition(@definition, association_name)
+    end
+
+    def validate_polymorphic_type(association_name, type)
+      ResourceLoader.find(type)
+    rescue ResourceLoader::MissingResourceClass
+      raise ArgumentError,
+            "Invalid relationship type for #{association_name}: '#{type}' does not have a resource class defined"
+    end
+
+    def validate_non_polymorphic_type(association_name, type, association)
+      expected_type = RelationshipHelpers.model_type_name(association.klass)
+      return if type == expected_type
+
+      raise ArgumentError, "Invalid relationship type for #{association_name}: expected #{expected_type}, got #{type}"
+    end
+
+    def extract_id(resource_identifier)
+      id = RelationshipHelpers.extract_id_from_identifier(resource_identifier)
+      raise ArgumentError, "Missing id in relationship data" unless id
+
+      id
+    end
+
+    def extract_type(resource_identifier)
+      type = RelationshipHelpers.extract_type_from_identifier(resource_identifier)
+      raise ArgumentError, "Missing type in relationship data" unless type
+
+      type
+    end
+
+    def valid_relationship_data?(data)
+      if data.is_a?(Array)
+        data.all? { |r| valid_resource_identifier?(r) }
+      else
+        valid_resource_identifier?(data)
+      end
+    end
+
+    def valid_resource_identifier?(identifier)
+      return false unless identifier.is_a?(Hash)
+
+      has_id?(identifier) && has_type?(identifier)
+    end
+
+    def has_id?(identifier)
+      identifier[:id]
+    end
+
+    def has_type?(identifier)
+      identifier[:type]
+    end
+
+    def resource_model_class
+      @model_class
+    end
+
+    def active_storage_attachment?(association_name)
+      return false unless @model_class
+
+      self.class.active_storage_attachment?(association_name, @model_class)
+    end
+
+    def ensure_relationship_writable!(association_name)
+      return if active_storage_attachment?(association_name)
+
+      association = @model_class.reflect_on_association(association_name.to_sym)
+      readonly = relationship_options_for(association_name)[:readonly] == true
+      JSONAPI::RelationshipGuard.ensure_writable!(association, association_name, readonly:) if association
+    end
+
+    def relationship_options_for(association_name)
+      relationship_def = RelationshipHelpers.find_relationship_definition(@definition, association_name)
+      return {} unless relationship_def
+
+      relationship_def[:options] || {}
+    end
+  end
+end