jsonapi_responses 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a729df17b8e8b391b9813a8a5c33234f9ff41893b52e4e25709a0df6e424e67
-  data.tar.gz: 533245b43a98e243764f278a5a0290ca7e6d6d35307a068393e2db0492432f9f
+  metadata.gz: ab50f413d2756f7f1f6b1faae376ebaf041a60fef7df43b29c037cfdfff295c2
+  data.tar.gz: a3921894b3f3c0a3565e4be39667c4c9f643b9837c35c1a1e8c9c1ac491c477d
 SHA512:
-  metadata.gz: 4abb25e296611f19b14379bb81c463d83210028ed4115453f100afa493d817234ea754e3f19211f7008bb4ab35347e4ee02516e26c44644260864aa68fb6cdba
-  data.tar.gz: 3a8e7416b1017a718b505e041287a75512ec3aec5d73ed60e132c16d1c204a688cf135004c30ebb45c79df731c4be6f22d6fe76f2f3cf3e916c9ed10380129da
+  metadata.gz: 0bfebe0f3f65b8125776d5161b7c26ac0d673ae979e8ca84ebca91422ef895812260e857ee43404c5a684eeec2e816258397229d25f172b3b4875d311cd6b979
+  data.tar.gz: 83a0979577818624cabe42b395c12df5c1ea594768a855469ecd9de0673911bc6b6843731020f21931b81da35f8eb83582d9d99f826f19d13cfc52381d3e9955

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 ## [Unreleased]
 
+## [1.1.0] - 2025-11-21
+
+### Added
+
+- **Automatic Pagination Support**: `respond_for_index` now auto-detects Kaminari/WillPaginate pagination and includes meta automatically
+- **Pagination Helpers in Responder**: Added `paginated?`, `pagination_meta`, and `render_collection_with_meta` methods
+- **Smart Meta Handling**: Automatically merges pagination meta with context meta if both are present
+
+### Features
+
+- Auto-detection of paginated collections (checks for `current_page`, `total_pages`, `total_count` methods)
+- Automatic inclusion of pagination metadata: `current_page`, `total_pages`, `total_count`, `per_page`
+- Backward compatible - works with manual `meta` in context or auto-detects pagination
+- Works with both Kaminari and WillPaginate gems
+
+### Example Usage
+
+```ruby
+# Controller - Automatic pagination meta
+def index
+  @academies = Academy.page(params[:page]).per(15)
+  render_with(@academies) # Auto-includes pagination meta!
+end
+
+# Manual meta still works
+def index
+  @academies = Academy.page(params[:page]).per(15)
+  render_with(@academies, context: { meta: { custom: 'data' } })
+  # Merges pagination + custom meta
+end
+
+# Custom responder with pagination helper
+class MyResponder < JsonapiResponses::Responder
+  def render
+    render_collection_with_meta(record, { custom: 'meta' })
+  end
+end
+```
+
 ## [1.0.0] - 2025-10-07
 
 ### 🎉 Major Release - Breaking Changes

data/README.md

@@ -153,6 +153,154 @@ By allowing the frontend to request only the needed data, you can:
 - Avoid creating multiple endpoints for different data requirements
 - Optimize database queries based on the requested view
 
+## Automatic Pagination Support
+
+**New in v1.1.0:** JsonapiResponses now automatically detects and handles paginated collections using Kaminari, making pagination effortless.
+
+### Basic Usage
+
+When you paginate your records with Kaminari, pagination metadata is automatically included in the response:
+
+```ruby
+class Api::V1::AcademiesController < ApplicationController
+  include JsonapiResponses::Respondable
+
+  def index
+    academies = Academy.page(params[:page]).per(15)
+    
+    # That's it! Pagination is automatic
+    render_with(academies)
+  end
+end
+```
+
+**Response:**
+
+```json
+{
+  "data": [
+    { "id": 1, "name": "Academy 1", ... },
+    { "id": 2, "name": "Academy 2", ... }
+  ],
+  "meta": {
+    "current_page": 1,
+    "total_pages": 5,
+    "total_count": 73,
+    "per_page": 15
+  }
+}
+```
+
+### How It Works
+
+JsonapiResponses automatically detects if your collection responds to Kaminari's pagination methods:
+- `current_page`
+- `total_pages`
+- `total_count`
+
+If these methods exist, pagination metadata is automatically included in the response.
+
+### With Custom Views
+
+Pagination works seamlessly with different view formats:
+
+```ruby
+def index
+  academies = Academy
+    .includes(:owner, :courses)
+    .page(params[:page])
+    .per(params[:per_page] || 15)
+  
+  # Supports view parameter and automatic pagination
+  render_with(academies)
+end
+```
+
+**Request:**
+```
+GET /api/v1/academies?page=2&per_page=20&view=summary
+```
+
+**Response:**
+```json
+{
+  "data": [
+    { "id": 21, "name": "Academy 21", ... }
+  ],
+  "meta": {
+    "current_page": 2,
+    "total_pages": 4,
+    "total_count": 73,
+    "per_page": 20
+  }
+}
+```
+
+### Requirements
+
+- **Kaminari gem** must be installed and configured
+- Your collection must be paginated with `.page()` method
+
+### Custom Pagination Metadata
+
+You can add additional metadata alongside automatic pagination:
+
+```ruby
+def index
+  academies = Academy.page(params[:page]).per(15)
+  
+  render_with(
+    academies,
+    context: { view: view },
+    meta: { 
+      fetched_at: Time.current,
+      filters_applied: params[:search].present?
+    }
+  )
+end
+```
+
+**Response:**
+```json
+{
+  "data": [...],
+  "meta": {
+    "current_page": 1,
+    "total_pages": 5,
+    "total_count": 73,
+    "per_page": 15,
+    "fetched_at": "2024-01-15T10:30:00Z",
+    "filters_applied": true
+  }
+}
+```
+
+### Using Pagination Helpers
+
+For custom responders, use the built-in pagination helpers:
+
+```ruby
+class AcademyResponder < JsonapiResponses::Responder
+  def respond_for_index
+    if paginated?(record)
+      render json: {
+        data: serialize_collection(record, serializer_class, context),
+        meta: pagination_meta(record, context)
+      }
+    else
+      render json: {
+        data: serialize_collection(record, serializer_class, context)
+      }
+    end
+  end
+end
+```
+
+Available helpers:
+- `paginated?(record)` - Check if record supports pagination
+- `pagination_meta(record, context)` - Extract pagination metadata hash
+- `render_collection_with_meta(record, serializer_class, context)` - Render with automatic pagination
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/jsonapi_responses/respondable.rb

@@ -212,7 +212,17 @@ module JsonapiResponses
     end
 
     def respond_for_index(record, serializer_class, context)
-      render json: serialize_collection(record, serializer_class, context)
+      response = { data: serialize_collection(record, serializer_class, context) }
+      
+      # Auto-detect pagination and add meta if available
+      if paginated?(record)
+        response[:meta] = pagination_meta(record, context)
+      elsif context[:meta]
+        # Allow manual meta from context
+        response[:meta] = context[:meta]
+      end
+      
+      render json: response
     end
 
     def respond_for_show(record, serializer_class, context)
@@ -259,5 +269,25 @@ module JsonapiResponses
         ]
       }, status: :bad_request
     end
+
+    # Check if record is paginated (Kaminari or WillPaginate support)
+    def paginated?(record)
+      record.respond_to?(:current_page) && 
+      record.respond_to?(:total_pages) &&
+      record.respond_to?(:total_count)
+    end
+
+    # Extract pagination metadata from paginated record
+    def pagination_meta(record, context = {})
+      base_meta = {
+        current_page: record.current_page,
+        total_pages: record.total_pages,
+        total_count: record.total_count,
+        per_page: record.try(:limit_value) || record.try(:per_page) || context[:per_page]
+      }.compact
+      
+      # Merge with any additional meta from context
+      context[:meta] ? base_meta.merge(context[:meta]) : base_meta
+    end
   end
 end

data/lib/jsonapi_responses/responder.rb

@@ -101,5 +101,49 @@ module JsonapiResponses
     def single_item?
       !collection?
     end
+
+    # Check if record is paginated (Kaminari or WillPaginate support)
+    # @return [Boolean]
+    def paginated?
+      record.respond_to?(:current_page) && 
+      record.respond_to?(:total_pages) &&
+      record.respond_to?(:total_count)
+    end
+
+    # Extract pagination metadata from paginated record
+    # @return [Hash, nil] Pagination metadata or nil if not paginated
+    def pagination_meta
+      return nil unless paginated?
+      
+      {
+        current_page: record.current_page,
+        total_pages: record.total_pages,
+        total_count: record.total_count,
+        per_page: record.try(:limit_value) || record.try(:per_page)
+      }.compact
+    end
+
+    # Render collection with automatic pagination support
+    # @param records [Array, ActiveRecord::Relation] Records to render
+    # @param additional_meta [Hash] Additional metadata to include
+    def render_collection_with_meta(records = nil, additional_meta = {})
+      records ||= record
+      response = { data: serialize_collection(records) }
+      
+      # Auto-detect pagination
+      if records.respond_to?(:current_page)
+        meta = {
+          current_page: records.current_page,
+          total_pages: records.total_pages,
+          total_count: records.total_count,
+          per_page: records.try(:limit_value) || records.try(:per_page)
+        }.compact
+        response[:meta] = meta.merge(additional_meta)
+      elsif additional_meta.any?
+        response[:meta] = additional_meta
+      end
+      
+      render_json(response)
+    end
   end
 end

data/lib/jsonapi_responses/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi_responses
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Oscar Ortega
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-10-08 00:00:00.000000000 Z
+date: 2025-11-22 00:00:00.000000000 Z
 dependencies: []
 description: JsonapiResponses simplifies API response handling by allowing multiple
   response formats from a single endpoint, improving performance and reducing endpoint