jpie 1.0.0 → 1.0.1

data/lib/json_api/serialization/concerns/deserialization_helpers.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Serialization
+    module DeserializationHelpers
+      private
+
+      def association_param_name(association_name)
+        return association_name.singularize unless @model_class
+
+        association = @model_class.reflect_on_association(association_name.to_sym)
+        return association_name.singularize unless association
+
+        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
+end

data/lib/json_api/serialization/concerns/includes_serialization.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Serialization
+    module IncludesSerialization
+      def serialize_included(includes, fields = {})
+        return [] if includes.empty?
+
+        included_records = []
+        processed = Set.new
+
+        includes.each do |include_path|
+          serialize_include_path(record, include_path, fields, included_records, processed)
+        end
+
+        included_records
+      end
+
+      private
+
+      def serialize_include_path(current_record, include_path, fields, included_records, processed)
+        path_parts = include_path.split(".")
+        association_name = path_parts.first.to_sym
+
+        return unless valid_include_association?(current_record, association_name)
+
+        related_array = get_related_records(current_record, association_name)
+        related_array.each do |related_record|
+          serialize_and_process_record(related_record, fields, included_records, processed)
+          serialize_nested_path(related_record, path_parts, fields, included_records, processed)
+        end
+      end
+
+      def valid_include_association?(current_record, association_name)
+        current_definition = ResourceLoader.find_for_model(current_record.class)
+        relationship_def = RelationshipHelpers.find_relationship_definition(current_definition, association_name)
+        return false unless relationship_def
+        return true if self.class.active_storage_attachment?(association_name, current_record.class)
+
+        association = current_record.class.reflect_on_association(association_name)
+        association.present?
+      end
+
+      def get_related_records(current_record, association_name)
+        if self.class.active_storage_attachment?(association_name, current_record.class)
+          return get_active_storage_records(current_record, association_name)
+        end
+
+        related = current_record.public_send(association_name)
+        Array(related)
+      end
+
+      def get_active_storage_records(current_record, association_name)
+        attachment = current_record.public_send(association_name)
+        return [] unless attachment.respond_to?(:attached?) && attachment.attached?
+        return attachment.blobs.to_a if attachment.is_a?(::ActiveStorage::Attached::Many)
+
+        [attachment.blob].compact
+      end
+
+      def serialize_and_process_record(related_record, fields, included_records, processed)
+        record_key = build_record_key(related_record)
+        return if processed.include?(record_key)
+
+        serializer = self.class.new(related_record)
+        included_records << serializer.serialize_record(fields)
+        processed.add(record_key)
+      end
+
+      def build_record_key(related_record)
+        "#{related_record.class.name}-#{related_record.id}"
+      end
+
+      def serialize_nested_path(related_record, path_parts, fields, included_records, processed)
+        return unless path_parts.length > 1
+
+        nested_path = path_parts[1..].join(".")
+        serialize_include_path(related_record, nested_path, fields, included_records, processed)
+      end
+    end
+  end
+end

data/lib/json_api/serialization/concerns/links_serialization.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Serialization
+    module LinksSerialization
+      def serialize_links
+        links = { self: "/#{record_type}/#{record_id}" }
+        add_active_storage_download_link(links) if active_storage_blob?
+        links
+      end
+
+      private
+
+      def active_storage_blob?
+        defined?(::ActiveStorage) && record.is_a?(::ActiveStorage::Blob)
+      end
+
+      def add_active_storage_download_link(links)
+        links[:download] = rails_blob_path || fallback_blob_path
+      rescue StandardError
+        links[:download] = fallback_blob_path
+      end
+
+      def rails_blob_path
+        Rails.application.routes.url_helpers.rails_blob_path(record, only_path: true)
+      end
+
+      def fallback_blob_path
+        "/rails/active_storage/blobs/#{record.signed_id}/#{record.filename}"
+      end
+    end
+  end
+end

data/lib/json_api/serialization/concerns/meta_serialization.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Serialization
+    module MetaSerialization
+      def record_meta
+        custom_meta = custom_meta_from_definition
+        default_meta = build_default_meta
+
+        return unless default_meta.any? || custom_meta.any?
+
+        default_meta.merge(custom_meta)
+      end
+
+      private
+
+      def custom_meta_from_definition
+        meta = fetch_instance_meta || fetch_class_meta
+        normalize_meta(meta)
+      end
+
+      def fetch_instance_meta
+        return unless definition.method_defined?(:meta)
+
+        instance = definition.new(@record, {})
+        instance.meta
+      end
+
+      def fetch_class_meta
+        class_meta = definition.resource_meta
+        return unless class_meta
+
+        class_meta.is_a?(Proc) ? class_meta.call(record) : class_meta
+      end
+
+      def normalize_meta(meta)
+        meta = meta.to_h if meta.respond_to?(:to_h) && !meta.is_a?(Hash)
+        meta || {}
+      end
+
+      def build_default_meta
+        default_timestamp_meta
+      end
+
+      def default_timestamp_meta
+        {}.tap do |meta|
+          meta[:created_at] = format_timestamp(:created_at)
+          meta[:updated_at] = format_timestamp(:updated_at)
+        end.compact
+      end
+
+      def format_timestamp(attr)
+        return unless record.respond_to?(attr)
+
+        value = record.public_send(attr)
+        value&.iso8601
+      end
+    end
+  end
+end

data/lib/json_api/serialization/concerns/model_attributes_transformation.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Serialization
+    module ModelAttributesTransformation
+      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
+    end
+  end
+end

data/lib/json_api/serialization/concerns/relationship_processing.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Serialization
+    module RelationshipProcessing
+      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
+
+      private
+
+      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)
+        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)
+        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) }
+
+        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
+    end
+  end
+end

data/lib/json_api/serialization/concerns/relationships_deserialization.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Serialization
+    module RelationshipsDeserialization
+      def relationships
+        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
+    end
+  end
+end

data/lib/json_api/serialization/concerns/relationships_serialization.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Serialization
+    module RelationshipsSerialization
+      def serialize_relationships
+        relationships = {}
+        relationship_definitions = definition.relationship_definitions
+
+        relationship_definitions.each do |rel_def|
+          serialize_relationship(rel_def, relationships)
+        end
+
+        relationships
+      end
+
+      private
+
+      def serialize_relationship(rel_def, relationships)
+        association_name = rel_def[:name]
+
+        if active_storage_attachment?(association_name, record.class)
+          return serialize_active_storage_relationship_wrapper(rel_def, relationships, association_name)
+        end
+
+        serialize_regular_relationship(rel_def, relationships, association_name)
+      end
+
+      def serialize_active_storage_relationship_wrapper(rel_def, relationships, association_name)
+        result = { data: serialize_active_storage_relationship(association_name, record) }
+        result[:meta] = rel_def[:meta] if rel_def[:meta].present?
+        relationships[association_name] = result
+      end
+
+      def serialize_regular_relationship(rel_def, relationships, association_name)
+        association = record.class.reflect_on_association(association_name)
+        return unless association
+
+        result = { data: serialize_relationship_data(association) }
+        result[:meta] = rel_def[:meta] if rel_def[:meta].present?
+        relationships[association_name] = result
+      end
+
+      def serialize_relationship_data(association)
+        related = record.public_send(association.name)
+
+        if association.collection?
+          serialize_collection_relationship(related, association)
+        elsif related
+          serialize_single_relationship(related, association)
+        end
+      end
+
+      def serialize_collection_relationship(related, association)
+        return [] if related.nil?
+
+        related.map { |r| serialize_identifier_for_related(r, association) }
+      end
+
+      def serialize_single_relationship(related, association)
+        serialize_identifier_for_related(related, association)
+      end
+
+      def serialize_identifier_for_related(related_record, association)
+        base_def_for_related, use_instance_class = determine_sti_definition(related_record)
+
+        RelationshipHelpers.serialize_resource_identifier(
+          related_record,
+          association:,
+          resource_class: definition,
+          use_instance_class:,
+          base_resource_class: base_def_for_related,
+        )
+      end
+
+      def determine_sti_definition(_related_record)
+        [nil, true]
+      end
+    end
+  end
+end