jpie 0.3.0

data/lib/jpie/resource/attributable.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module JPie
+  class Resource
+    module Attributable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_attributes, :_relationships, :_meta_attributes
+        self._attributes = []
+        self._relationships = {}
+        self._meta_attributes = []
+      end
+
+      class_methods do
+        def attribute(name, options = {}, &)
+          name = name.to_sym
+          _attributes << name unless _attributes.include?(name)
+          define_attribute_method(name, options, &)
+        end
+
+        def attributes(*names)
+          names.each { attribute(it) }
+        end
+
+        def meta_attribute(name, options = {}, &)
+          name = name.to_sym
+          _meta_attributes << name unless _meta_attributes.include?(name)
+          define_attribute_method(name, options, &)
+        end
+
+        def meta_attributes(*names)
+          names.each { meta_attribute(it) }
+        end
+
+        # More concise aliases for modern Rails style
+        alias_method :meta, :meta_attribute
+        alias_method :metas, :meta_attributes
+
+        def relationship(name, options = {})
+          name = name.to_sym
+          _relationships[name] = options
+
+          # Check if method is already defined (public or private) to allow custom implementations
+          return if method_defined?(name) || private_method_defined?(name)
+
+          define_method(name) do
+            attr_name = options[:attr] || name
+            @object.public_send(attr_name)
+          end
+        end
+
+        def has_many(name, options = {})
+          name = name.to_sym
+          resource_class_name = options[:resource] || infer_resource_class_name(name)
+          relationship(name, { resource: resource_class_name }.merge(options))
+        end
+
+        def has_one(name, options = {})
+          name = name.to_sym
+          resource_class_name = options[:resource] || infer_resource_class_name(name)
+          relationship(name, { resource: resource_class_name }.merge(options))
+        end
+
+        private
+
+        def define_attribute_method(name, options, &)
+          # If a block is provided, use it (existing behavior)
+          if block_given?
+            define_method(name) do
+              instance_exec(&)
+            end
+          # If options[:block] is provided, use it (existing behavior)
+          elsif options[:block]
+            define_method(name) do
+              instance_exec(&options[:block])
+            end
+          # If method is not already defined on the resource (public or private), define the default implementation
+          elsif !method_defined?(name) && !private_method_defined?(name)
+            define_method(name) do
+              attr_name = options[:attr] || name
+              @object.public_send(attr_name)
+            end
+          end
+          # If method is already defined, don't override it - let the custom method handle it
+        end
+
+        def infer_resource_class_name(relationship_name)
+          # Convert relationship name to resource class name
+          # :posts -> "PostResource"
+          # :user -> "UserResource"
+          singularized_name = relationship_name.to_s.singularize
+          "#{singularized_name.camelize}Resource"
+        end
+      end
+    end
+  end
+end

data/lib/jpie/resource/inferrable.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module JPie
+  class Resource
+    module Inferrable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_type, :_model_class
+      end
+
+      class_methods do
+        def model(model_class = nil)
+          if model_class
+            self._model_class = model_class
+          else
+            _model_class || infer_model_class
+          end
+        end
+
+        def type(type_name = nil)
+          if type_name
+            self._type = type_name.to_s
+          else
+            _type || infer_type_name
+          end
+        end
+
+        private
+
+        def infer_model_class
+          name.chomp('Resource').constantize
+        rescue NameError
+          nil
+        end
+
+        def infer_type_name
+          model&.model_name&.plural || name.chomp('Resource').underscore.pluralize
+        end
+      end
+    end
+  end
+end

data/lib/jpie/resource/sortable.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module JPie
+  class Resource
+    module Sortable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_sortable_fields
+        self._sortable_fields = {}
+      end
+
+      class_methods do
+        # Define a sortable field with optional custom sorting logic
+        # Example:
+        #   sortable_by :name
+        #   sortable_by :created_at, :created_at_desc
+        #   sortable_by :popularity do |direction|
+        #     if direction == :asc
+        #       model.order(:likes_count)
+        #     else
+        #       model.order(likes_count: :desc)
+        #     end
+        #   end
+        def sortable_by(field, column = nil, &block)
+          field = field.to_sym
+          _sortable_fields[field] = block || column || field
+        end
+
+        # More concise alias for modern Rails style
+        alias_method :sortable, :sortable_by
+
+        # Apply sorting to a query based on sort parameters
+        # sort_fields: array of sort field strings (e.g., ['name', '-created_at'])
+        def sort(query, sort_fields)
+          return query if sort_fields.blank?
+
+          sort_fields.each do |sort_field|
+            # Parse direction (- prefix means descending)
+            if sort_field.start_with?('-')
+              field = sort_field[1..].to_sym
+              direction = :desc
+            else
+              field = sort_field.to_sym
+              direction = :asc
+            end
+
+            # Check if field is sortable
+            unless sortable_field?(field)
+              raise JPie::Errors::BadRequestError.new(
+                detail: "Invalid sort field: #{field}. Sortable fields are: #{sortable_fields.join(', ')}"
+              )
+            end
+
+            # Apply sorting
+            query = apply_sort(query, field, direction)
+          end
+
+          query
+        end
+
+        # Get list of all sortable fields (attributes + explicitly defined sortable fields)
+        def sortable_fields
+          (_attributes + _sortable_fields.keys).uniq.map(&:to_s)
+        end
+
+        # Check if a field is sortable
+        def sortable_field?(field)
+          field = field.to_sym
+          _attributes.include?(field) || _sortable_fields.key?(field)
+        end
+
+        private
+
+        # Apply a single sort to the query
+        def apply_sort(query, field, direction)
+          sortable_config = _sortable_fields[field]
+
+          if sortable_config.is_a?(Proc)
+            # Custom sorting block
+            instance_exec(query, direction, &sortable_config)
+          elsif sortable_config.is_a?(Symbol)
+            # Custom column name
+            query.order(sortable_config => direction)
+          else
+            # Default sorting by attribute name
+            query.order(field => direction)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jpie/resource.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative 'resource/attributable'
+require_relative 'resource/inferrable'
+require_relative 'resource/sortable'
+require_relative 'errors'
+
+module JPie
+  class Resource
+    include ActiveSupport::Configurable
+    include Attributable
+    include Inferrable
+    include Sortable
+
+    class << self
+      def inherited(subclass)
+        super
+        subclass._attributes = _attributes.dup
+        subclass._relationships = _relationships.dup
+        subclass._meta_attributes = _meta_attributes.dup
+        subclass._sortable_fields = _sortable_fields.dup
+      end
+
+      # Default scope method that returns all records
+      # Override this in your resource classes to provide authorization scoping
+      # Example:
+      #   def self.scope(context)
+      #     current_user = context[:current_user]
+      #     return model.none unless current_user
+      #
+      #     if current_user.admin?
+      #       model.all
+      #     else
+      #       model.where(user: current_user)
+      #     end
+      #   end
+      def scope(_context = {})
+        model.all
+      end
+    end
+
+    attr_reader :object, :context
+
+    def initialize(object, context = {})
+      @object = object
+      @context = context
+    end
+
+    delegate :id, to: :@object
+
+    delegate :type, to: :class
+
+    def attributes_hash
+      self.class._attributes.index_with do
+        send(it)
+      end
+    end
+
+    def meta_hash
+      # Start with meta attributes from the macro
+      base_meta = self.class._meta_attributes.index_with do
+        send(it)
+      end
+
+      # Check if the resource defines a custom meta method
+      if respond_to?(:meta, true) && method(:meta).owner != JPie::Resource
+        custom_meta = meta
+
+        # Validate that meta method returns a hash
+        unless custom_meta.is_a?(Hash)
+          raise JPie::Errors::ResourceError.new(
+            detail: "meta method must return a Hash, got #{custom_meta.class}"
+          )
+        end
+
+        # Merge custom meta with base meta (custom meta takes precedence)
+        base_meta.merge(custom_meta)
+      else
+        base_meta
+      end
+    end
+
+    protected
+
+    # Default meta method that returns the meta attributes
+    # This can be overridden in subclasses
+    def meta
+      self.class._meta_attributes.index_with do
+        send(it)
+      end
+    end
+
+    private
+
+    def method_missing(method_name, *, &)
+      if @object.respond_to?(method_name)
+        @object.public_send(method_name, *, &)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @object.respond_to?(method_name, include_private) || super
+    end
+  end
+end

data/lib/jpie/serializer.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module JPie
+  class Serializer
+    attr_reader :resource_class, :options
+
+    def initialize(resource_class, options = {})
+      @resource_class = resource_class
+      @options = options
+    end
+
+    def serialize(objects, context = {}, includes: [])
+      return { data: nil } if objects.nil?
+
+      resources = build_resources(objects, context)
+      result = serialize_data(objects, resources)
+      add_included_data(result, resources, includes, context) if should_include_data?(includes, result)
+      result
+    end
+
+    private
+
+    def build_resources(objects, context)
+      Array(objects).filter_map { |obj| obj ? resource_class.new(obj, context) : nil }
+    end
+
+    def serialize_data(objects, resources)
+      if objects.is_a?(Array) || objects.respond_to?(:each)
+        serialize_collection(resources)
+      else
+        resources.first ? serialize_single(resources.first) : { data: nil }
+      end
+    end
+
+    def should_include_data?(includes, result)
+      includes.any? && result[:data]
+    end
+
+    def add_included_data(result, resources, includes, context)
+      included_data = collect_included_data(resources, includes, context)
+      result[:included] = included_data
+    end
+
+    def serialize_single(resource)
+      {
+        data: serialize_resource_data(resource)
+      }
+    end
+
+    def serialize_collection(resources)
+      {
+        data: resources.map { serialize_resource_data(it) }
+      }
+    end
+
+    def serialize_resource_data(resource)
+      data = {
+        id: resource.id.to_s,
+        type: resource.type,
+        attributes: serialize_attributes(resource)
+      }
+
+      meta_data = serialize_meta(resource)
+      data[:meta] = meta_data if meta_data.any?
+
+      data.compact
+    end
+
+    def serialize_attributes(resource)
+      attributes = resource.attributes_hash
+      return {} if attributes.empty?
+
+      attributes.transform_keys { it.to_s.underscore }
+                .transform_values { serialize_value(it) }
+    end
+
+    def serialize_meta(resource)
+      meta_attributes = resource.meta_hash
+      return {} if meta_attributes.empty?
+
+      meta_attributes.transform_keys { it.to_s.underscore }
+                     .transform_values { serialize_value(it) }
+    end
+
+    def serialize_value(value)
+      value.respond_to?(:iso8601) ? value.iso8601 : value
+    end
+
+    def collect_included_data(resources, includes, context)
+      processor = IncludeProcessor.new(self, context)
+      processor.process(resources, includes)
+    end
+
+    def parse_nested_includes(includes)
+      result = {}
+
+      includes.each do |include_path|
+        parts = include_path.split('.')
+        top_level = parts.first
+        nested_path = parts[1..].join('.') if parts.length > 1
+
+        result[top_level] ||= []
+        result[top_level] << nested_path if nested_path.present?
+      end
+
+      result
+    end
+
+    # Helper class to manage include processing state and reduce parameter passing
+    class IncludeProcessor
+      attr_reader :serializer, :context, :included, :processed_includes
+
+      def initialize(serializer, context)
+        @serializer = serializer
+        @context = context
+        @included = []
+        @processed_includes = {}
+      end
+
+      def process(resources, includes)
+        parsed_includes = serializer.send(:parse_nested_includes, includes)
+        parsed_includes.each do |include_name, nested_includes|
+          process_single_include(include_name, nested_includes, resources)
+        end
+        included
+      end
+
+      private
+
+      def process_single_include(include_name, nested_includes, resources)
+        include_sym = include_name.to_sym
+        relationship_options = serializer.resource_class._relationships[include_sym]
+        return unless relationship_options
+
+        resources.each do |resource|
+          process_resource_relationships(resource, include_sym, relationship_options, nested_includes)
+        end
+      end
+
+      def process_resource_relationships(resource, include_sym, relationship_options, nested_includes)
+        related_objects = resource.public_send(include_sym)
+        return unless related_objects
+
+        Array(related_objects).each do |related_object|
+          process_related_object(related_object, relationship_options, nested_includes)
+        end
+      end
+
+      def process_related_object(related_object, relationship_options, nested_includes)
+        related_resource_class = serializer.send(:determine_resource_class, related_object, relationship_options)
+        return unless related_resource_class
+
+        related_resource = related_resource_class.new(related_object, context)
+        resource_data = serializer.send(:serialize_resource_data, related_resource)
+
+        add_to_included_if_unique(resource_data)
+        process_nested_includes_for_resource(related_resource_class, related_resource, nested_includes)
+      end
+
+      def add_to_included_if_unique(resource_data)
+        key = [resource_data[:type], resource_data[:id]]
+        return if processed_includes[key]
+
+        processed_includes[key] = true
+        included << resource_data
+      end
+
+      def process_nested_includes_for_resource(related_resource_class, related_resource, nested_includes)
+        return unless nested_includes.any?
+
+        nested_serializer = JPie::Serializer.new(related_resource_class)
+        nested_included = nested_serializer.send(:collect_included_data, [related_resource], nested_includes, context)
+
+        nested_included.each do |nested_item|
+          add_to_included_if_unique(nested_item)
+        end
+      end
+    end
+
+    def determine_resource_class(object, relationship_options)
+      # First try the explicitly specified resource class
+      if relationship_options[:resource]
+        begin
+          return relationship_options[:resource].constantize
+        rescue NameError
+          # If the resource class doesn't exist, it might be a polymorphic relationship
+          # Fall through to polymorphic detection
+        end
+      end
+
+      # For polymorphic relationships, determine resource class from object class
+      if object&.class
+        resource_class_name = "#{object.class.name}Resource"
+        begin
+          return resource_class_name.constantize
+        rescue NameError
+          # Resource class doesn't exist for this object type
+          return nil
+        end
+      end
+
+      nil
+    end
+  end
+end

data/lib/jpie/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JPie
+  VERSION = '0.3.0'
+end

data/lib/jpie.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext'
+require 'jpie/version'
+
+module JPie
+  autoload :Resource, 'jpie/resource'
+  autoload :Serializer, 'jpie/serializer'
+  autoload :Deserializer, 'jpie/deserializer'
+  autoload :Controller, 'jpie/controller'
+  autoload :Configuration, 'jpie/configuration'
+  autoload :Errors, 'jpie/errors'
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end
+
+require 'jpie/railtie' if defined?(Rails)