respondo 0.1.0 → 2.0.0

data/lib/respondo/pagination.rb

@@ -1,94 +1,152 @@
-# frozen_string_literal: true
+# # frozen_string_literal: true
 
-module Respondo
-  # Extracts pagination metadata from Kaminari or Pagy collection objects.
-  #
-  # Returned hash shape (always the same regardless of pagination library):
-  #   {
-  #     current_page:  Integer,
-  #     per_page:      Integer,
-  #     total_pages:   Integer,
-  #     total_count:   Integer,
-  #     next_page:     Integer | nil,
-  #     prev_page:     Integer | nil
-  #   }
-  module Pagination
-    module_function
+# module Respondo
+#   # Extracts pagination metadata from Kaminari, Pagy, or WillPaginate collections.
+#   #
+#   # --- How pagination works in Respondo ---
+#   #
+#   # Respondo does NOT paginate data for you. Pagination is always performed by
+#   # your chosen library (Kaminari, Pagy, or WillPaginate) in your controller
+#   # BEFORE you call render_success / render_ok.
+#   #
+#   # Respondo's role is purely to DETECT that the collection is paginated and
+#   # EXTRACT the metadata so it appears in the `meta.pagination` block.
+#   #
+#   # --- Usage patterns by library ---
+#   #
+#   # Kaminari (pagination lives on the collection itself):
+#   #   @users = User.page(params[:page]).per(params[:per_page] || 10)
+#   #   render_ok(data: @users)          # ← just pass the collection; Respondo detects Kaminari
+#   #
+#   # WillPaginate (same — pagination lives on the collection):
+#   #   @users = User.paginate(page: params[:page], per_page: 10)
+#   #   render_ok(data: @users)          # ← same pattern
+#   #
+#   # Pagy (metadata lives on a SEPARATE Pagy object, not the collection):
+#   #   @pagy, @users = pagy(User.all, items: 10)
+#   #   render_ok(data: @users, pagy: @pagy)   # ← pass the Pagy object explicitly
+#   #
+#   #   Alternatively, if you decorate your collection with pagy_metadata:
+#   #   render_ok(data: @pagy)           # ← pass the Pagy object as data (unusual)
+#   #
+#   # --- Returned hash shape (same regardless of library) ---
+#   #   {
+#   #     current_page:  Integer,
+#   #     per_page:      Integer,
+#   #     total_pages:   Integer,
+#   #     total_count:   Integer,
+#   #     next_page:     Integer | nil,
+#   #     prev_page:     Integer | nil
+#   #   }
+#   #
+#   # --- Disabling pagination meta ---
+#   # Pass pagination: false to any render_* helper to suppress the block entirely:
+#   #   render_ok(data: @users, pagination: false)
+#   #
+#   module Pagination
+#     module_function
 
-    # @param collection [Object] any object — returns nil if not a paginated collection
-    # @return [Hash, nil]
-    def extract(collection)
-      return nil if collection.nil?
+#     # @param collection [Object] any object — returns nil if not a paginated collection
+#     # @return [Hash, nil]
+#     def extract(collection)
+#       return nil if collection.nil?
 
-      if pagy?(collection)
-        from_pagy(collection)
-      elsif kaminari?(collection)
-        from_kaminari(collection)
-      elsif will_paginate?(collection)
-        from_will_paginate(collection)
-      else
-        nil
-      end
-    end
+#       if pagy?(collection)
+#         from_pagy(collection)
+#       elsif kaminari?(collection)
+#         from_kaminari(collection)
+#       elsif will_paginate?(collection)
+#         from_will_paginate(collection)
+#       else
+#         nil
+#       end
+#     end
 
-    private
+#     private
 
-    module_function
+#     module_function
 
-    # ----- Pagy ---------------------------------------------------------------
-    # Pagy stores metadata on a separate Pagy object, not the collection itself.
-    # We support both: passing the Pagy object directly, or a collection that
-    # has been decorated with pagy metadata via pagy_metadata.
-    def pagy?(object)
-      defined?(Pagy) && object.is_a?(Pagy)
-    end
+#     # -------------------------------------------------------------------------
+#     # Pagy
+#     # -------------------------------------------------------------------------
+#     # Pagy stores metadata on a SEPARATE Pagy object, not the collection.
+#     # You must pass it explicitly via the `pagy:` keyword in render_success/render_ok.
+#     #
+#     # Example in controller:
+#     #   @pagy, @records = pagy(User.all, items: 10)
+#     #   render_ok(data: @records, pagy: @pagy)
+#     #
+#     def pagy?(object)
+#       defined?(Pagy) && object.is_a?(Pagy)
+#     end
 
-    def from_pagy(pagy)
-      {
-        current_page: pagy.page,
-        per_page:     pagy.items,
-        total_pages:  pagy.pages,
-        total_count:  pagy.count,
-        next_page:    pagy.next,
-        prev_page:    pagy.prev
-      }
-    end
+#     def from_pagy(pagy)
+#       {
+#         current_page: pagy.page,
+#         per_page:     pagy.items,
+#         total_pages:  pagy.pages,
+#         total_count:  pagy.count,
+#         next_page:    pagy.next,
+#         prev_page:    pagy.prev
+#       }
+#     end
 
-    # ----- Kaminari -----------------------------------------------------------
-    def kaminari?(object)
-      object.respond_to?(:current_page) &&
-        object.respond_to?(:total_pages) &&
-        object.respond_to?(:limit_value)
-    end
+#     # -------------------------------------------------------------------------
+#     # Kaminari
+#     # -------------------------------------------------------------------------
+#     # Kaminari attaches pagination directly to the ActiveRecord relation.
+#     # No extra argument needed — just pass the collection.
+#     #
+#     # Example in controller:
+#     #   @records = User.page(params[:page]).per(10)
+#     #   render_ok(data: @records)
+#     #
+#     def kaminari?(object)
+#       object.respond_to?(:current_page) &&
+#         object.respond_to?(:total_pages) &&
+#         object.respond_to?(:limit_value)
+#     end
 
-    def from_kaminari(collection)
-      {
-        current_page: collection.current_page,
-        per_page:     collection.limit_value,
-        total_pages:  collection.total_pages,
-        total_count:  collection.total_count,
-        next_page:    collection.next_page,
-        prev_page:    collection.prev_page
-      }
-    end
+#     def from_kaminari(collection)
+#       {
+#         current_page: collection.current_page,
+#         per_page:     collection.limit_value,
+#         total_pages:  collection.total_pages,
+#         total_count:  collection.total_count,
+#         next_page:    collection.next_page,
+#         prev_page:    collection.prev_page
+#       }
+#     end
 
-    # ----- WillPaginate -------------------------------------------------------
-    def will_paginate?(object)
-      object.respond_to?(:current_page) &&
-        object.respond_to?(:total_pages) &&
-        object.respond_to?(:per_page) &&
-        !object.respond_to?(:limit_value) # distinguishes from Kaminari
-    end
+#     # -------------------------------------------------------------------------
+#     # WillPaginate
+#     # -------------------------------------------------------------------------
+#     # WillPaginate also attaches pagination to the collection.
+#     # No extra argument needed — just pass the collection.
+#     #
+#     # Example in controller:
+#     #   @records = User.paginate(page: params[:page], per_page: 10)
+#     #   render_ok(data: @records)
+#     #
+#     # We distinguish WillPaginate from Kaminari by the absence of #limit_value.
+#     #
+#     def will_paginate?(object)
+#       object.respond_to?(:current_page) &&
+#         object.respond_to?(:total_pages) &&
+#         object.respond_to?(:per_page) &&
+#         !object.respond_to?(:limit_value)
+#     end
+
+#     def from_will_paginate(collection)
+#       {
+#         current_page: collection.current_page,
+#         per_page:     collection.per_page,
+#         total_pages:  collection.total_pages,
+#         total_count:  collection.total_entries,
+#         next_page:    collection.next_page,
+#         prev_page:    collection.previous_page
+#       }
+#     end
+#   end
+# end
 
-    def from_will_paginate(collection)
-      {
-        current_page: collection.current_page,
-        per_page:     collection.per_page,
-        total_pages:  collection.total_pages,
-        total_count:  collection.total_entries,
-        next_page:    collection.next_page,
-        prev_page:    collection.previous_page
-      }
-    end
-  end
-end

data/lib/respondo/response_builder.rb

@@ -17,24 +17,24 @@ module Respondo
   #   { timestamp: ISO8601 String }
   # Plus pagination keys when pagination: true and the data is a paginated collection.
   # Plus request_id when config.include_request_id is true.
+  # Plus pagination when a pagination hash is supplied by the caller.
   class ResponseBuilder
     # @param success    [Boolean]
     # @param data       [Object]   anything — serialized automatically
     # @param message    [String]
     # @param meta       [Hash]     caller-supplied extra meta (merged in)
     # @param errors     [Hash]     field-level errors (for 422 responses)
-    # @param pagy       [Pagy]     optional Pagy object for pagination meta
-    # @param pagination [Boolean]  true = include pagination meta (default),
-    #                              false = always suppress pagination meta
+    # @param pagination [Hash, nil] plain pagination hash supplied by the caller, e.g.
+    #                               { current_page: 1, per_page: 25, total_pages: 4,
+    #                                 total_count: 100, next_page: 2, prev_page: nil }
     # @param request    [Object]   ActionDispatch::Request (for request_id)
     def initialize(success:, data: nil, message: nil, meta: {}, errors: nil,
-                   pagy: nil, pagination: true, request: nil)
+                   pagination: nil, request: nil)
       @success    = success
       @raw_data   = data
       @message    = message
       @extra_meta = meta || {}
       @errors     = errors
-      @pagy       = pagy
       @pagination = pagination
       @request    = request
     end
@@ -69,27 +69,56 @@ module Respondo
     end
 
     def build_meta
-      meta = { timestamp: current_timestamp }
-
-      # Only extract pagination when caller has not explicitly disabled it
-      if @pagination
-        pagination = if @pagy
-          Pagination.extract(@pagy)
-        else
-          Pagination.extract(@raw_data)
-        end
-        meta[:pagination] = pagination if pagination
-      end
+      meta = {}
 
-      # Request ID (Rails only, opt-in via config)
+      # 1. Request ID first (opt-in, always authoritative)
       if Respondo.config.include_request_id && @request&.respond_to?(:request_id)
         meta[:request_id] = @request.request_id
       end
 
-      # Merge any caller-supplied meta last (allows overriding)
-      meta.merge(@extra_meta)
+      # 2. Timestamp second
+      meta[:timestamp] = current_timestamp
+
+      # 3. Global defaults in the middle (lowest priority)
+      meta.merge!(Respondo.config.default_meta)
+
+      # 4. Caller-supplied meta (overrides defaults)
+      meta.merge!(@extra_meta)
+
+      # 5. Pagination — plain hash from the caller, placed last before code/status
+      meta[:pagination] = @pagination if @pagination.is_a?(Hash) && !@pagination.empty?
+
+      # 6. Re-pin code and status to the very end
+      code   = meta.delete(:code)
+      status = meta.delete(:status)
+      meta[:code]   = code   if code
+      meta[:status] = status if status
+
+      meta
     end
 
+    # def build_meta
+    #   meta = { timestamp: current_timestamp }
+
+    #   # Only extract pagination when caller has not explicitly disabled it
+    #   if @pagination
+    #     pagination = if @pagy
+    #       Pagination.extract(@pagy)
+    #     else
+    #       Pagination.extract(@raw_data)
+    #     end
+    #     meta[:pagination] = pagination if pagination
+    #   end
+
+    #   # Request ID (Rails only, opt-in via config)
+    #   if Respondo.config.include_request_id && @request&.respond_to?(:request_id)
+    #     meta[:request_id] = @request.request_id
+    #   end
+
+    #   # Merge any caller-supplied meta last (allows overriding)
+    #   meta.merge(@extra_meta)
+    # end
+
     def current_timestamp
       if defined?(Time.current)
         Time.current.iso8601

data/lib/respondo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Respondo
-  VERSION = "0.1.0"
+  VERSION = "2.0.0"
 end

data/lib/respondo.rb

@@ -3,7 +3,7 @@
 require_relative "respondo/version"
 require_relative "respondo/configuration"
 require_relative "respondo/serializer"
-require_relative "respondo/pagination"
+# require_relative "respondo/pagination"
 require_relative "respondo/response_builder"
 require_relative "respondo/controller_helpers"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: respondo
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - shailendra Kumar
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec