jpie 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 654010b56dc91dbc6edffc3c54891d7d6cb7eab738f685cbbe0e793aa9d26b13
-  data.tar.gz: d400665267796d760e1051697a46bb067c414142be5372e1abb2ac1254e8aaa7
+  metadata.gz: 1f2984708bbd678f90b58e39d28e853f93b504b933cd15f8af8a995c21eb41e4
+  data.tar.gz: 4b6107778dc307c1f155bf013b372dd05db8e0891f1b1a39c8b4ebdc96f4b42c
 SHA512:
-  metadata.gz: a4081700e8daa2cd9e4b209d7cf2d1d0464b44d3678fb9095adc995fe5e075ad5fa00b64af8bc7bdb9a53177f64ba74e999e85f61d56c9c82d2908bede76b579
-  data.tar.gz: 6c786599fbfda71820206e62c17dbbb9ed86d28858ae905293b20a9426e3cf64da76dba69c8ffaa7dfff5193f4e42ba203a09ba635943f8ac6212cea95bdfada
+  metadata.gz: 8393c4ba329b198d648f7bb2260777e0c889fde78e8d592ae72cfd9cd48ca97cdacfd0453214011f47cbff7af67c634dba001c888ca1447462f1263460f691c5
+  data.tar.gz: f42ea311ec1bea10f6e13d2c30af99eba23369fcc97ffa6a29acdfd2af74b6c109171fee4bed3b880edabc67e2157c950857d5a0fbac85b78bf55c94b57676e1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jpie (1.2.0)
+    jpie (1.3.0)
       actionpack (~> 8.0, >= 8.0.0)
       rails (~> 8.0, >= 8.0.0)
 

data/PERFORMANCE_BASELINE.md

@@ -0,0 +1,102 @@
+# jpie Performance Baseline
+
+This document outlines the performance metrics for key operations within the `jpie` gem, comparing the initial baseline with the results after implementing all optimizations.
+
+## Performance Comparison
+
+| Metric | Original Baseline | After Optimizations | Improvement |
+|--------|-------------------|---------------------|-------------|
+| `resource_loader_find_avg_ms` | 0.0182 | 0.0003 | **60x faster** |
+| `resource_loader_find_for_model_avg_ms` | 0.036 | 0.0003 | **120x faster** |
+| `jsonapi_object_avg_ms` | 0.0003 | 0.0001 | **3x faster** |
+| `serialize_single_user_avg_ms` | 0.2168 | 0.0982 | **2.2x faster** |
+| `serialize_10_users_avg_ms` | 1.4318 | 0.975 | **1.5x faster** |
+| `serialize_single_user_query_count` | 4 | 4 | N/A |
+| `serialize_10_users_query_count` | 40 | 40 | N/A |
+| `serialize_single_user_allocations` | 997 | 977 | **2% reduction** |
+| `serialize_10_users_allocations` | 9934 | 9716 | **2% reduction** |
+| `relationship_definitions_avg_ms` | 0.0036 | 0.0002 | **18x faster** |
+| `resource_instantiation_avg_ms` | 0.0003 | 0.0004 | Similar |
+
+## Implemented Optimizations
+
+### 1. ResourceLoader Caching (Phase 4)
+- Thread-safe caching for `find` and `find_for_model` methods
+- Eliminates repeated `constantize` calls
+- **60-120x improvement** in resource class lookups
+
+### 2. jsonapi_object Memoization (Phase 5)
+- Memoized the static JSON:API object
+- Returns frozen object to prevent mutations
+- **3x improvement** in object generation
+
+### 3. Relationship Definitions Caching (Phase 6)
+- Memoized `relationship_definitions` computation
+- Returns frozen array to prevent mutations
+- **18x improvement** in relationship metadata access
+
+### 4. Optional Count Query (Phase 7)
+- `total_count` only computed when pagination is applied
+- Avoids unnecessary COUNT queries for non-paginated requests
+- Reduces database load
+
+### 5. Eager Loading DSL (Phase 8)
+- New `eager_load` class method for resources
+- Automatically included in preloading without explicit `include` param
+- Helps eliminate N+1 queries at the resource level
+
+### 6. Preload for Serialization Hook (Phase 9)
+- New `preload_for_serialization` class method
+- Called before serialization with all records
+- Enables batch-loading of data needed by `meta` methods
+- Thread-local storage for preloaded data
+
+## Usage Examples
+
+### Eager Loading DSL
+
+```ruby
+class WorkstreamResource < ApplicationResource
+  eager_load :conversation, :owners
+
+  # These associations will be automatically eager-loaded
+  # even without an explicit ?include= param
+end
+```
+
+### Preload for Serialization Hook
+
+```ruby
+class WorkstreamResource < ApplicationResource
+  def self.preload_for_serialization(records, context = {})
+    # Batch-load stats for all records
+    stats = Preloaders::StatsPreloader.call(records: records)
+    stats  # Store in preloaded_data for access in meta
+  end
+
+  def meta(...)
+    stats = self.class.preloaded_data[record.id] || record.loading_stats
+    super.merge(loading: stats)
+  end
+end
+```
+
+## Metric Interpretation
+
+- **`resource_loader_find_avg_ms`**: Average time to find a resource class by type
+- **`resource_loader_find_for_model_avg_ms`**: Average time to find a resource class by model
+- **`jsonapi_object_avg_ms`**: Average time to generate the static `jsonapi` object
+- **`serialize_single_user_avg_ms`**: Average time to serialize a single `User` record
+- **`serialize_10_users_avg_ms`**: Average time to serialize a collection of 10 `User` records
+- **`serialize_single_user_query_count`**: Number of SQL queries for single `User` serialization
+- **`serialize_10_users_query_count`**: Number of SQL queries for 10 `User` records serialization
+- **`serialize_single_user_allocations`**: Object allocations for single `User` serialization
+- **`serialize_10_users_allocations`**: Object allocations for 10 `User` records serialization
+- **`relationship_definitions_avg_ms`**: Average time to compute relationship definitions
+- **`resource_instantiation_avg_ms`**: Average time to instantiate a resource
+
+## Notes
+
+- Query counts remain the same in benchmarks as they test the serializer directly
+- Real-world N+1 reduction comes from the `eager_load` DSL and `preload_for_serialization` hook
+- Allocation reduction is modest but consistent across serialization

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

@@ -6,10 +6,9 @@ module JSONAPI
       extend ActiveSupport::Concern
 
       def preload_includes
-        includes = parse_include_param
-        return if includes.empty?
+        includes_hash = build_combined_includes_hash
+        return if includes_hash.empty?
 
-        includes_hash = build_includes_hash(includes)
         preload_resources(includes_hash)
       rescue ActiveRecord::RecordNotFound
         # Will be handled by set_resource
@@ -17,6 +16,23 @@ module JSONAPI
 
       private
 
+      def build_combined_includes_hash
+        param_includes = parse_include_param
+        dsl_includes = resource_eager_load_associations
+
+        combined = dsl_includes.map(&:to_s)
+        combined.concat(param_includes)
+        combined.uniq!
+
+        build_includes_hash(combined)
+      end
+
+      def resource_eager_load_associations
+        return [] unless resource_class.respond_to?(:eager_load_associations)
+
+        resource_class.eager_load_associations
+      end
+
       def build_includes_hash(includes)
         includes.each_with_object({}) do |path, hash|
           merge_include_path(hash, path)
@@ -24,7 +40,7 @@ module JSONAPI
       end
 
       def merge_include_path(hash, path)
-        parts = path.split(".")
+        parts = path.to_s.split(".")
         current = hash
 
         parts.each_with_index do |part, i|

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

@@ -6,14 +6,29 @@ module JSONAPI
       extend ActiveSupport::Concern
 
       def serialize_resource(resource)
+        run_preload_hook([resource])
         JSONAPI::Serializer.new(resource).to_hash(
           include: parse_include_param,
           fields: parse_fields_param,
           document_meta: jsonapi_document_meta,
         )
+      ensure
+        clear_preload_data
       end
 
       def serialize_collection(resources)
+        resources_array = resources.to_a
+        run_preload_hook(resources_array)
+
+        data, all_included = serialize_resources_with_includes(resources_array)
+        build_collection_response(data, all_included)
+      ensure
+        clear_preload_data
+      end
+
+      private
+
+      def serialize_resources_with_includes(resources)
         includes = parse_include_param
         fields = parse_fields_param
         all_included = []
@@ -25,11 +40,9 @@ module JSONAPI
           result[:data]
         end
 
-        build_collection_response(data, all_included)
+        [data, all_included]
       end
 
-      private
-
       def serialize_single(resource, includes, fields)
         JSONAPI::Serializer.new(resource).to_hash(include: includes, fields:, document_meta: nil)
       end
@@ -58,6 +71,21 @@ module JSONAPI
 
         result
       end
+
+      def run_preload_hook(records)
+        return unless resource_class.respond_to?(:preload_for_serialization)
+
+        preloaded = resource_class.preload_for_serialization(records, jsonapi_context)
+        resource_class.preloaded_data = preloaded if preloaded.present?
+      end
+
+      def clear_preload_data
+        resource_class.clear_preloaded_data! if resource_class.respond_to?(:clear_preloaded_data!)
+      end
+
+      def jsonapi_context
+        { current_user: respond_to?(:current_user) ? current_user : nil }
+      end
     end
   end
 end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Resources
+    module EagerLoadDsl
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Declare associations to always eager-load for this resource
+        # @param associations [Array<Symbol>] list of association names to eager-load
+        def eager_load(*associations)
+          @declared_eager_loads ||= []
+          @declared_eager_loads.concat(associations.map(&:to_sym))
+          reset_eager_load_associations!
+        end
+
+        # Get all eager-load associations including inherited ones
+        # @return [Array<Symbol>] frozen array of association names
+        def eager_load_associations
+          return @eager_load_associations if defined?(@eager_load_associations)
+
+          @eager_load_associations = build_eager_load_associations.freeze
+        end
+
+        def reset_eager_load_associations!
+          remove_instance_variable(:@eager_load_associations) if defined?(@eager_load_associations)
+        end
+      end
+
+      module EagerLoadHelperMethods
+        def build_eager_load_associations
+          own_associations = @declared_eager_loads || []
+          inherited = inherit_eager_load_associations
+          (inherited + own_associations).uniq
+        end
+
+        def inherit_eager_load_associations
+          return [] unless superclass.respond_to?(:eager_load_associations)
+          return [] if superclass == JSONAPI::Resource
+
+          superclass.eager_load_associations
+        end
+      end
+
+      included do
+        extend EagerLoadHelperMethods
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Resources
+    module PreloadDsl
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Override this method in resource subclasses to preload data before serialization.
+        # This is called once with all records before serialization starts.
+        # Use this to batch-load data needed by meta methods to avoid N+1 queries.
+        #
+        # @param records [Array<ActiveRecord::Base>] the records that will be serialized
+        # @param context [Hash] optional context (e.g., current user, request params)
+        # @return [Hash] a hash of preloaded data keyed by record id
+        #
+        # @example
+        #   class WorkstreamResource < ApplicationResource
+        #     def self.preload_for_serialization(records, context = {})
+        #       stats = Preloaders::StatsPreloader.call(records: records)
+        #       { stats: stats }
+        #     end
+        #
+        #     def meta(...)
+        #       preloaded = self.class.preloaded_data[record.id]
+        #       super.merge(loading: preloaded[:stats])
+        #     end
+        #   end
+        def preload_for_serialization(_records, _context = {})
+          # Default implementation does nothing - override in subclasses
+          {}
+        end
+
+        # Storage for preloaded data (request-scoped via Thread.current)
+        def preloaded_data
+          Thread.current["#{name}_preloaded_data"] ||= {}
+        end
+
+        def preloaded_data=(data)
+          Thread.current["#{name}_preloaded_data"] = data
+        end
+
+        def clear_preloaded_data!
+          Thread.current["#{name}_preloaded_data"] = nil
+        end
+      end
+    end
+  end
+end

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

@@ -7,29 +7,30 @@ module JSONAPI
 
       class_methods do
         def has_one(name, meta: nil, **options)
-          @relationships ||= []
           detect_polymorphic(name, options)
-          @relationships << { name: name.to_sym, type: :has_one, meta:, options: }
+          register_relationship(name:, type: :has_one, meta:, options:)
         end
 
         def has_many(name, meta: nil, **options)
-          @relationships ||= []
           validate_append_only_options!(options)
           detect_polymorphic(name, options)
-          @relationships << { name: name.to_sym, type: :has_many, meta:, options: }
+          register_relationship(name:, type: :has_many, meta:, options:)
         end
 
         def belongs_to(name, meta: nil, **options)
-          @relationships ||= []
           detect_polymorphic(name, options)
-          @relationships << { name: name.to_sym, type: :belongs_to, meta:, options: }
+          register_relationship(name:, type: :belongs_to, meta:, options:)
         end
 
         def relationship_definitions
-          declared_relationships = instance_variable_defined?(:@relationships)
-          rels = @relationships || []
-          rels = superclass.relationship_definitions + rels if should_inherit_relationships?(declared_relationships)
-          rels.uniq { |r| r[:name] }
+          return @relationship_definitions if defined?(@relationship_definitions)
+
+          rels = build_relationship_definitions
+          @relationship_definitions = rels.freeze
+        end
+
+        def reset_relationship_definitions!
+          remove_instance_variable(:@relationship_definitions) if defined?(@relationship_definitions)
         end
 
         def relationship_names
@@ -38,6 +39,19 @@ module JSONAPI
       end
 
       module RelationshipHelperMethods
+        def register_relationship(name:, type:, meta:, options:)
+          @relationships ||= []
+          @relationships << { name: name.to_sym, type:, meta:, options: }
+          reset_relationship_definitions!
+        end
+
+        def build_relationship_definitions
+          declared_relationships = instance_variable_defined?(:@relationships)
+          rels = @relationships || []
+          rels = superclass.relationship_definitions + rels if should_inherit_relationships?(declared_relationships)
+          rels.uniq { |r| r[:name] }
+        end
+
         def validate_append_only_options!(options)
           if options[:append_only] && options[:purge_on_nil] == true
             raise ArgumentError, "Cannot use append_only: true with purge_on_nil: true"

data/lib/json_api/resources/resource.rb

@@ -6,6 +6,8 @@ require_relative "concerns/sortable_fields_dsl"
 require_relative "concerns/relationships_dsl"
 require_relative "concerns/meta_dsl"
 require_relative "concerns/model_class_helpers"
+require_relative "concerns/eager_load_dsl"
+require_relative "concerns/preload_dsl"
 
 module JSONAPI
   class Resource
@@ -15,6 +17,8 @@ module JSONAPI
     include Resources::RelationshipsDsl
     include Resources::MetaDsl
     include Resources::ModelClassHelpers
+    include Resources::EagerLoadDsl
+    include Resources::PreloadDsl
 
     class << self
       attr_accessor :type_format

data/lib/json_api/resources/resource_loader.rb

@@ -16,7 +16,25 @@ module JSONAPI
       end
     end
 
+    # Thread-safe caches for resource class lookups
+    # Using simple Hash with ||= is safe enough - worst case is duplicate computation
+    # which is acceptable since the result is always the same Class object
+    @find_cache = {}
+    @model_cache = {}
+
+    class << self
+      def clear_cache!
+        @find_cache = {}
+        @model_cache = {}
+      end
+    end
+
     def self.find(resource_type, namespace: nil)
+      cache_key = "#{namespace}::#{resource_type}"
+      @find_cache[cache_key] ||= find_uncached(resource_type, namespace:)
+    end
+
+    def self.find_uncached(resource_type, namespace: nil)
       return find_namespaced(resource_type, namespace) if namespace.present?
 
       find_flat(resource_type, namespace)
@@ -48,7 +66,8 @@ module JSONAPI
     def self.find_for_model(model_class, namespace: nil)
       return ActiveStorageBlobResource if active_storage_blob?(model_class)
 
-      find_resource_for_model(model_class, namespace)
+      cache_key = "#{namespace}::#{model_class.name}"
+      @model_cache[cache_key] ||= find_resource_for_model(model_class, namespace)
     end
 
     def self.find_resource_for_model(model_class, namespace)

data/lib/json_api/serialization/serializer.rb

@@ -17,12 +17,22 @@ module JSONAPI
 
     JSONAPI_VERSION = "1.1"
 
+    @jsonapi_object = nil
+
     def self.jsonapi_object
+      @jsonapi_object ||= build_jsonapi_object.freeze
+    end
+
+    def self.build_jsonapi_object
       obj = { version: JSONAPI_VERSION }
       obj[:meta] = JSONAPI.configuration.jsonapi_meta if JSONAPI.configuration.jsonapi_meta
       obj
     end
 
+    def self.reset_jsonapi_object!
+      @jsonapi_object = nil
+    end
+
     def initialize(record, definition: nil, base_definition: nil)
       @record = record
       @definition = definition || ResourceLoader.find_for_model(record.class)

data/lib/json_api/support/collection_query.rb

@@ -30,10 +30,8 @@ module JSONAPI
 
     def execute
       @scope = apply_filtering
-      has_virtual_sort = sort_params.any? { |sort_field| virtual_attribute_sort?(sort_field) }
-      @total_count = @scope.count unless has_virtual_sort
+      compute_total_count_if_needed
       @scope = apply_sorting(@scope)
-      @total_count = @scope.count if has_virtual_sort && @scope.is_a?(Array)
       @scope = apply_pagination
       self
     end
@@ -42,6 +40,14 @@ module JSONAPI
 
     attr_reader :definition, :model_class, :filter_params, :sort_params, :page_params
 
+    def compute_total_count_if_needed
+      return unless pagination_applied
+
+      has_virtual_sort = sort_params.any? { |sort_field| virtual_attribute_sort?(sort_field) }
+      @total_count = @scope.count unless has_virtual_sort
+      @total_count = @scope.count if has_virtual_sort && @scope.is_a?(Array)
+    end
+
     def apply_filtering
       scope = apply_nested_relationship_filters(@scope)
       apply_regular_filters(scope)

data/lib/json_api/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Emil Kampp
@@ -64,6 +64,7 @@ files:
 - ".travis.yml"
 - Gemfile
 - Gemfile.lock
+- PERFORMANCE_BASELINE.md
 - README.md
 - Rakefile
 - bin/console
@@ -105,9 +106,11 @@ files:
 - lib/json_api/railtie.rb
 - lib/json_api/resources/active_storage_blob_resource.rb
 - lib/json_api/resources/concerns/attributes_dsl.rb
+- lib/json_api/resources/concerns/eager_load_dsl.rb
 - lib/json_api/resources/concerns/filters_dsl.rb
 - lib/json_api/resources/concerns/meta_dsl.rb
 - lib/json_api/resources/concerns/model_class_helpers.rb
+- lib/json_api/resources/concerns/preload_dsl.rb
 - lib/json_api/resources/concerns/relationships_dsl.rb
 - lib/json_api/resources/concerns/sortable_fields_dsl.rb
 - lib/json_api/resources/resource.rb