jsonapi_responses 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0699dc3667f281c640290126057003d615a2925420486b95bf4c6b6ca0498493'
-  data.tar.gz: 2ad39e4993c900b4d675fcba5cf45065d7b467a34f06c6e99d7e6a246dc87010
+  metadata.gz: 9a729df17b8e8b391b9813a8a5c33234f9ff41893b52e4e25709a0df6e424e67
+  data.tar.gz: 533245b43a98e243764f278a5a0290ca7e6d6d35307a068393e2db0492432f9f
 SHA512:
-  metadata.gz: c9272215b1f4238ab65d30e961a928d1d20307287e1d3b82a9dbbe79f0f08c63567973e3b38cde93777064f20c8d0d977541910cf2b3433604eef0891a662e3b
-  data.tar.gz: 6b2f625abcbe757534d222f16a1edcbbdd24f1947f5071a6f26c7ad1b2745fe188c51f54d69aaf777124e8af3eacb33a8769a9bc701c3538cf95623fbdc013f7
+  metadata.gz: 4abb25e296611f19b14379bb81c463d83210028ed4115453f100afa493d817234ea754e3f19211f7008bb4ab35347e4ee02516e26c44644260864aa68fb6cdba
+  data.tar.gz: 3a8e7416b1017a718b505e041287a75512ec3aec5d73ed60e132c16d1c204a688cf135004c30ebb45c79df731c4be6f22d6fe76f2f3cf3e916c9ed10380129da

data/CHANGELOG.md

@@ -7,11 +7,13 @@
 This is a major release with significant architectural improvements and breaking changes.
 
 ### Breaking Changes
+
 - **Renamed `BaseSerializer`** → `ApplicationSerializer` (follows Rails convention)
 - **Renamed `BaseResponder`** → `ApplicationResponder` (follows Rails convention like ApplicationPolicy)
 - Responders now follow **Pundit-style pattern**: one responder class per controller with multiple action methods
 
 ### Added
+
 - **Pundit-Style Responders**: One responder class per controller (e.g., `AcademyResponder`, `CourseResponder`)
 - **Action-based method calls**: Use `render_with(@records, responder: AcademyResponder, action: :featured)`
 - **ApplicationResponder base class**: With common helpers like `render_collection_with_meta`, `base_meta`, `filters_applied`
@@ -43,7 +45,7 @@ class AcademyResponder < ApplicationResponder
   def featured  # ← Method instead of render
     # ...
   end
-  
+
   def popular
     # ...
   end
@@ -63,6 +65,7 @@ render_with(@academies, responder: AcademyResponder, action: :featured)
 #### 3. Consolidate Responders
 
 Instead of one file per action:
+
 ```
 # Before
 app/responders/academy_featured_responder.rb
@@ -74,7 +77,8 @@ app/responders/academy_responder.rb  # All methods inside
 ```
 
 ### Improved
-- Better alignment with Rails naming conventions (Application* prefix)
+
+- Better alignment with Rails naming conventions (Application\* prefix)
 - Reduced file proliferation (3-4 responder files instead of 20+)
 - Easier to maintain and understand (Pundit-style pattern)
 - Better code organization and discoverability
@@ -82,18 +86,18 @@ app/responders/academy_responder.rb  # All methods inside
 ## [0.3.0] - 2025-10-07
 
 ### Added
+
 - **Custom Responders System**: New architecture for handling complex custom actions
   - Added `JsonapiResponses::Responder` base class for creating dedicated responder objects
   - Responders encapsulate response logic, keeping controllers clean and promoting reusability
   - Full access to controller context, serialization helpers, and request params
-  
 - **Responder Base Class Features**:
   - `serialize_collection` and `serialize_item` helpers for data serialization
   - `render_json` helper for consistent JSON rendering
   - `collection?` and `single_item?` type checking utilities
   - Access to `params`, `current_user`, `controller`, `record`, `serializer_class`, and `context`
-  
 - **Enhanced render_with**:
+
   - New `responder:` parameter to use custom responder classes
   - New `serializer:` parameter to override default serializer detection
   - Example: `render_with(@records, responder: FeaturedResponder, serializer: CustomSerializer)`
@@ -104,17 +108,20 @@ app/responders/academy_responder.rb  # All methods inside
   - `CategorizedResponder` - For grouped/categorized responses
 
 ### Changed
+
 - Updated `lib/jsonapi_responses.rb` to require `responder.rb`
 - Enhanced `Respondable` module to support responder classes
 - Improved documentation with comprehensive Responder guide
 
 ### Documentation
+
 - Added "Custom Responders" section to README with complete examples
 - Added comparison table: when to use each approach (mapping vs methods vs responders)
 - Added `RESPONDERS_FEATURE.md` with complete implementation guide
 - Documented Responder API and best practices
 
 ### Benefits
+
 - **Separation of Concerns**: Response logic separated from controllers
 - **Reusability**: Same responder can be used across multiple controllers
 - **Testability**: Test response logic independently from controllers
@@ -123,31 +130,35 @@ app/responders/academy_responder.rb  # All methods inside
 ## [0.2.0] - 2025-10-06
 
 ### Added
+
 - **Custom Actions Support**: Support for custom actions beyond standard CRUD (index, show, create, update, destroy)
 - **Explicit Action Mapping**: `map_response_action` and `map_response_actions` for mapping custom actions to existing responses
 - **Metaprogramming Support**: Dynamic method generation for response handlers
   - `define_response_for`: Define custom response methods using blocks
   - `define_responses_for`: Define same behavior for multiple actions in batch
   - `define_crud_responses`: Intelligent CRUD responses with dynamic context
-  - `generate_rest_responses`: Auto-generate namespaced REST responses (public_, admin_, etc.)
+  - `generate_rest_responses`: Auto-generate namespaced REST responses (public*, admin*, etc.)
 - **Dynamic Context**: Support for lambdas/procs in context generation with `instance_eval`
 - **Method Introspection**: `response_definitions` class attribute for debugging generated methods
 - **Enhanced Error Messages**: Detailed error responses with suggestions when actions are not supported
 
 ### Changed
+
 - **Breaking**: Removed automatic fallback behavior for action mapping (by design - explicit is better than implicit)
 - **Improved**: `render_invalid_action` now provides detailed error information with actionable suggestions
 - **Enhanced**: Better error handling with specific guidance on how to implement missing methods
 
 ### Technical Details
+
 - Added `class_attribute :response_definitions` for storing method definitions
 - Enhanced `render_with` method resolution to support custom and mapped actions
 - All generated methods are properly marked as private
 - Full backward compatibility maintained for existing CRUD operations
 
 ### Documentation
+
 - Added comprehensive documentation in CUSTOM_ACTIONS.md
-- Added metaprogramming guide in METAPROGRAMMING.md  
+- Added metaprogramming guide in METAPROGRAMMING.md
 - Added practical implementation example in PRACTICAL_EXAMPLE.md
 - Updated README with new functionality overview
 

data/README.md

@@ -147,6 +147,7 @@ GET /api/v1/digital_products?view=minimal  # Returns minimal response
 ### Performance Benefits
 
 By allowing the frontend to request only the needed data, you can:
+
 - Reduce response payload size
 - Improve API performance
 - Avoid creating multiple endpoints for different data requirements
@@ -165,14 +166,15 @@ Beyond the standard CRUD actions (index, show, create, update, destroy), you can
 ### Basic Usage
 
 **Option 1: Map to existing actions**
+
 ```ruby
 class Api::V1::CoursesController < ApplicationController
   include JsonapiResponses::Respondable
-  
+
   # Map custom actions to existing response methods
   map_response_action :public_index, to: :index
   map_response_action :public_show, to: :show
-  
+
   def public_index
     # Your logic here
     render_with(@courses)  # Will use respond_for_index
@@ -181,17 +183,18 @@ end
 ```
 
 **Option 2: Define custom response methods**
+
 ```ruby
 class Api::V1::CoursesController < ApplicationController
   include JsonapiResponses::Respondable
-  
+
   def dashboard_stats
     # Your logic here
     render_with(@stats)
   end
-  
+
   private
-  
+
   def respond_for_dashboard_stats(record, serializer_class, context)
     render json: {
       data: record,
@@ -202,17 +205,18 @@ end
 ```
 
 **Option 3: Metaprogramming (Recommended for complex scenarios)**
+
 ```ruby
 class Api::V1::CoursesController < ApplicationController
   include JsonapiResponses::Respondable
-  
+
   # Generate methods automatically
   generate_rest_responses(
     namespace: 'public',
     actions: [:index, :show],
     context: { access_level: 'public' }
   )
-  
+
   # Define similar responses in batch
   define_responses_for [:export_csv, :export_pdf] do |record, serializer_class, context|
     format = action_name.to_s.split('_').last
@@ -253,26 +257,26 @@ app/responders/
 # app/responders/application_responder.rb
 class ApplicationResponder < JsonapiResponses::Responder
   protected
-  
+
   def render_collection_with_meta(type: nil, additional_meta: {})
     render_json({
       data: serialize_collection(record),
       meta: base_meta.merge({ type: type }.compact).merge(additional_meta)
     })
   end
-  
+
   def base_meta
     {
       timestamp: Time.current.iso8601,
       count: record_count
     }.compact
   end
-  
+
   def record_count
     return nil unless collection?
     record.respond_to?(:count) ? record.count : record.size
   end
-  
+
   def filters_applied
     filter_keys = [:category_id, :level, :status]
     filters = {}
@@ -287,7 +291,7 @@ end
 ```ruby
 # app/responders/academy_responder.rb
 class AcademyResponder < ApplicationResponder
-  
+
   # GET /api/v1/academies/featured
   def featured
     if params[:category_id].present?
@@ -296,7 +300,7 @@ class AcademyResponder < ApplicationResponder
       render_all_featured
     end
   end
-  
+
   # GET /api/v1/academies/popular
   def popular
     render_collection_with_meta(
@@ -307,7 +311,7 @@ class AcademyResponder < ApplicationResponder
       }
     )
   end
-  
+
   # GET /api/v1/academies/recommended
   def recommended
     render_collection_with_meta(
@@ -318,9 +322,9 @@ class AcademyResponder < ApplicationResponder
       }
     )
   end
-  
+
   private
-  
+
   def render_filtered_featured
     render_json({
       data: serialize_collection(record),
@@ -330,7 +334,7 @@ class AcademyResponder < ApplicationResponder
       }
     })
   end
-  
+
   def render_all_featured
     render_collection_with_meta(type: 'featured')
   end
@@ -347,12 +351,12 @@ class Api::V1::AcademiesController < ApplicationController
     @academies = load_featured_academies
     render_with(@academies, responder: AcademyResponder, action: :featured)
   end
-  
+
   def popular
     @academies = Academy.popular.limit(20)
     render_with(@academies, responder: AcademyResponder, action: :popular)
   end
-  
+
   def recommended
     @academies = Academy.recommended_for(current_user)
     render_with(@academies, responder: AcademyResponder, action: :recommended)
@@ -363,12 +367,14 @@ end
 ### Benefits of This Pattern
 
 **Like Pundit Policies:**
+
 - ✅ One file per controller (not per action)
 - ✅ All related logic in one place
 - ✅ Easy to find and maintain
 - ✅ Shared helpers in base class
 
 **Example Structure:**
+
 ```
 AcademiesController → AcademyResponder (featured, popular, recommended)
 CoursesController   → CourseResponder (featured, search, progress)
@@ -384,18 +390,18 @@ class MyCustomResponder < JsonapiResponses::Responder
   def render
     # Access to controller instance
     controller.current_user
-    
+
     # Access to params
     params[:filter]
-    
+
     # Serialize data
     serialize_collection(record)  # For collections
     serialize_item(record)         # For single items
-    
+
     # Check record type
     collection?    # true if record is a collection
     single_item?   # true if record is a single item
-    
+
     # Render JSON
     render_json({ data: [], meta: {} })
   end
@@ -419,14 +425,14 @@ class CategorizedResponder < JsonapiResponses::Responder
   private
 
   def structured_data?
-    record.is_a?(Array) && 
-    record.first.is_a?(Hash) && 
+    record.is_a?(Array) &&
+    record.first.is_a?(Hash) &&
     record.first.key?(:category)
   end
 
   def group_by_category
     categories = {}
-    
+
     serialize_collection(record).each do |item|
       category_id = item.dig(:category, :id) || 'uncategorized'
       categories[category_id] ||= {
@@ -435,7 +441,7 @@ class CategorizedResponder < JsonapiResponses::Responder
       }
       categories[category_id][:items] << item
     end
-    
+
     categories.values.map do |group|
       group.merge(count: group[:items].size)
     end
@@ -445,12 +451,12 @@ end
 
 ### When to Use Each Approach
 
-| Approach | Best For | Complexity |
-|----------|----------|------------|
-| `map_response_action` | Simple actions similar to existing ones | Low |
-| `respond_for_*` methods | 1-2 custom actions with simple logic | Medium |
-| Custom Responders | 3+ custom actions or complex response logic | High |
-| Metaprogramming | Batch generation of similar actions | High |
+| Approach                | Best For                                    | Complexity |
+| ----------------------- | ------------------------------------------- | ---------- |
+| `map_response_action`   | Simple actions similar to existing ones     | Low        |
+| `respond_for_*` methods | 1-2 custom actions with simple logic        | Medium     |
+| Custom Responders       | 3+ custom actions or complex response logic | High       |
+| Metaprogramming         | Batch generation of similar actions         | High       |
 
 ### Mixing Approaches
 
@@ -459,23 +465,23 @@ You can combine different approaches in the same controller:
 ```ruby
 class Api::V1::ProductsController < ApplicationController
   include JsonapiResponses::Respondable
-  
+
   # Map simple actions
   map_response_action :public_index, to: :index
-  
+
   # Use responder for complex actions
   def featured
     @products = Product.featured
     render_with(@products, responder: FeaturedResponder)
   end
-  
+
   # Use custom method for one-off logic
   def statistics
     render_with(@stats)
   end
-  
+
   private
-  
+
   def respond_for_statistics(record, serializer_class, context)
     render json: { stats: record, generated_at: Time.current }
   end

data/app/responders/application_responder.rb

@@ -0,0 +1,99 @@
+# ApplicationResponder - Base class for all responders
+# 
+# This follows Rails convention (like ApplicationRecord, ApplicationController)
+# and Pundit pattern (like ApplicationPolicy).
+#
+# Create one responder per controller with multiple action methods inside.
+#
+# @example Creating a resource responder
+#   class ProductResponder < ApplicationResponder
+#     # GET /products/featured
+#     def featured
+#       render_collection_with_meta(
+#         type: 'featured',
+#         additional_meta: { category: params[:category_id] }
+#       )
+#     end
+#     
+#     # GET /products/popular
+#     def popular
+#       render_collection_with_meta(
+#         type: 'popular',
+#         additional_meta: { period: params[:period] || 'month' }
+#       )
+#     end
+#   end
+#
+# @example Using in controller
+#   class ProductsController < ApplicationController
+#     def featured
+#       @products = Product.featured
+#       render_with(@products, responder: ProductResponder, action: :featured)
+#     end
+#   end
+class ApplicationResponder < JsonapiResponses::Responder
+  # Common helper methods available to all responders
+  
+  protected
+  
+  # Render a standard collection with metadata
+  # @param type [String, Symbol] Type of collection (e.g., 'featured', 'popular')
+  # @param additional_meta [Hash] Additional metadata to include
+  def render_collection_with_meta(type: nil, additional_meta: {})
+    render_json({
+      data: serialize_collection(record),
+      meta: base_meta.merge({ type: type }.compact).merge(additional_meta)
+    })
+  end
+  
+  # Render a single item with metadata
+  # @param additional_meta [Hash] Additional metadata to include
+  def render_item_with_meta(additional_meta: {})
+    render_json({
+      data: serialize_item(record),
+      meta: base_meta.merge(additional_meta)
+    })
+  end
+  
+  # Render grouped/categorized data
+  # @param groups [Array, Hash] Pre-structured grouped data
+  def render_grouped_data(groups)
+    render_json(groups)
+  end
+  
+  # Base metadata common to all responses
+  # @return [Hash] Base metadata including timestamp and count
+  def base_meta
+    {
+      timestamp: Time.current.iso8601,
+      count: record_count
+    }.compact
+  end
+  
+  # Get the count of records
+  # @return [Integer, nil] Count if collection, nil otherwise
+  def record_count
+    return nil unless collection?
+    record.respond_to?(:count) ? record.count : record.size
+  end
+  
+  # Check if a parameter is present
+  # @param key [Symbol, String] Parameter key
+  # @return [Boolean]
+  def param_present?(key)
+    params[key].present?
+  end
+  
+  # Get filters applied from params
+  # @param filter_keys [Array<Symbol>] Keys to check for filters
+  # @return [Hash, nil] Hash of applied filters or nil if none
+  def filters_applied(filter_keys = [:category_id, :level, :status, :sort_by, :limit])
+    filters = {}
+    
+    filter_keys.each do |key|
+      filters[key] = params[key] if params[key].present?
+    end
+    
+    filters.empty? ? nil : filters
+  end
+end

data/app/serializers/application_serializer.rb

@@ -0,0 +1,88 @@
+# ApplicationSerializer - Base class for all serializers
+# 
+# This follows Rails convention (like ApplicationRecord, ApplicationController).
+# All your model serializers should inherit from this class.
+#
+# @example Creating a model serializer
+#   class ProductSerializer < ApplicationSerializer
+#     def serializable_hash
+#       case context[:view]
+#       when :summary
+#         summary_hash
+#       when :minimal
+#         minimal_hash
+#       else
+#         full_hash
+#       end
+#     end
+#     
+#     private
+#     
+#     def full_hash
+#       {
+#         id: resource.id,
+#         name: resource.name,
+#         description: resource.description,
+#         price: resource.price,
+#         created_at: resource.created_at
+#       }
+#     end
+#     
+#     def summary_hash
+#       {
+#         id: resource.id,
+#         name: resource.name,
+#         price: resource.price
+#       }
+#     end
+#     
+#     def minimal_hash
+#       {
+#         id: resource.id,
+#         name: resource.name
+#       }
+#     end
+#   end
+class ApplicationSerializer
+  attr_reader :resource, :context
+
+  # Initialize serializer with resource and optional context
+  # @param resource [Object] The object to serialize
+  # @param context [Hash] Additional context (e.g., current_user, view type)
+  def initialize(resource, context = {})
+    @resource = resource
+    @context = context
+  end
+
+  # Override this method in your serializers
+  # @return [Hash] Serialized representation of the resource
+  def serializable_hash
+    raise NotImplementedError, "#{self.class.name} must implement #serializable_hash"
+  end
+
+  # Access to current_user from context
+  # @return [User, nil]
+  def current_user
+    @context[:current_user]
+  end
+
+  # Access to view type from context
+  # @return [Symbol, nil] e.g., :summary, :minimal, :full
+  def view
+    @context[:view]
+  end
+
+  # Helper to serialize associations
+  # @param association [Object, Array] Association to serialize
+  # @param serializer_class [Class] Serializer class to use
+  # @return [Hash, Array<Hash>]
+  def serialize_association(association, serializer_class)
+    return nil if association.nil?
+    
+    if association.respond_to?(:map)
+      association.map { |item| serializer_class.new(item, context).serializable_hash }
+    else
+      serializer_class.new(association, context).serializable_hash
+    end
+  end
+end

data/lib/jsonapi_responses/responder.rb

@@ -0,0 +1,105 @@
+module JsonapiResponses
+  # Base class for custom responders
+  # Responders encapsulate response logic for custom actions,
+  # keeping controllers clean and promoting reusability.
+  #
+  # @example Basic usage
+  #   class FeaturedResponder < JsonapiResponses::Responder
+  #     def render
+  #       controller.render json: {
+  #         data: serialize_collection(record),
+  #         meta: {
+  #           type: 'featured',
+  #           count: record.count
+  #         }
+  #       }
+  #     end
+  #   end
+  #
+  # @example Using in controller
+  #   def featured
+  #     @academies = Academy.featured
+  #     render_with(@academies, responder: FeaturedResponder)
+  #   end
+  class Responder
+    attr_reader :controller, :record, :serializer_class, :context
+
+    # @param controller [ActionController::Base] The controller instance
+    # @param record [Object, Array, ActiveRecord::Relation] The record(s) to serialize
+    # @param serializer_class [Class] The serializer class to use
+    # @param context [Hash] Additional context for serialization
+    def initialize(controller, record, serializer_class, context = {})
+      @controller = controller
+      @record = record
+      @serializer_class = serializer_class
+      @context = context
+    end
+
+    # Render the response. Must be implemented by subclasses.
+    # @raise [NotImplementedError] if not implemented in subclass
+    def render
+      raise NotImplementedError, "#{self.class.name} must implement #render method"
+    end
+
+    protected
+
+    # Serialize a collection of records
+    # @param records [Array, ActiveRecord::Relation] Records to serialize
+    # @param custom_serializer [Class, nil] Optional custom serializer
+    # @param custom_context [Hash, nil] Optional custom context
+    # @return [Array<Hash>] Serialized collection
+    def serialize_collection(records = nil, custom_serializer = nil, custom_context = nil)
+      records ||= record
+      serializer = custom_serializer || serializer_class
+      ctx = custom_context || context
+      
+      controller.send(:serialize_collection, records, serializer, ctx)
+    end
+
+    # Serialize a single record
+    # @param item [Object] Record to serialize
+    # @param custom_serializer [Class, nil] Optional custom serializer
+    # @param custom_context [Hash, nil] Optional custom context
+    # @return [Hash] Serialized record
+    def serialize_item(item = nil, custom_serializer = nil, custom_context = nil)
+      item ||= record
+      serializer = custom_serializer || serializer_class
+      ctx = custom_context || context
+      
+      controller.send(:serialize_item, item, serializer, ctx)
+    end
+
+    # Access to params from the controller
+    # @return [ActionController::Parameters]
+    def params
+      controller.params
+    end
+
+    # Access to current_user from the controller (if available)
+    # @return [Object, nil]
+    def current_user
+      controller.respond_to?(:current_user, true) ? controller.send(:current_user) : nil
+    end
+
+    # Helper to render JSON directly through the controller
+    # @param data [Hash] Data to render
+    # @param options [Hash] Additional render options (status, etc.)
+    def render_json(data, options = {})
+      controller.render({ json: data }.merge(options))
+    end
+
+    # Helper to check if record is a collection
+    # @return [Boolean]
+    def collection?
+      record.is_a?(Array) || 
+      record.is_a?(ActiveRecord::Relation) ||
+      (record.respond_to?(:to_a) && !record.is_a?(Hash))
+    end
+
+    # Helper to check if record is a single item
+    # @return [Boolean]
+    def single_item?
+      !collection?
+    end
+  end
+end

data/lib/jsonapi_responses/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JsonapiResponses
-  VERSION = '1.0.0'.freeze
+  VERSION = '1.0.1'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi_responses
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Oscar Ortega
@@ -28,11 +28,14 @@ files:
 - README.md
 - Rakefile
 - app/models/item.rb
+- app/responders/application_responder.rb
+- app/serializers/application_serializer.rb
 - app/serializers/item_serializer.rb
 - config/database.yml
 - lib/jsonapi_responses.rb
 - lib/jsonapi_responses/engine.rb
 - lib/jsonapi_responses/respondable.rb
+- lib/jsonapi_responses/responder.rb
 - lib/jsonapi_responses/serializable.rb
 - lib/jsonapi_responses/user_context_provider.rb
 - lib/jsonapi_responses/version.rb