plan_my_stuff 0.27.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4162f792a9b4fbc7cced8a9a91721c21d15010189cf38021b87d20d53dbcb56
-  data.tar.gz: 72c6220c9be50c083360357ba28f1cb7225c784ed9c8813430e24e9e27736f04
+  metadata.gz: 9aac5ec777cf9b53a459843e9bdbf1177178fe1623457a60d266e993db3d2d93
+  data.tar.gz: 1b7089b760fa0552e3b861732472e43cab09667699e1528703809a2ce753254f
 SHA512:
-  metadata.gz: af715bae691caff87d81935e140a3bc2d4af7ef49780686f85b8f145ce9e7a6ff32a6ea689c697a4bc6d193ca0612ff7147a850ea5088876282c4a6bf284ab26
-  data.tar.gz: 94d67d34bc302ceb3ec4fa815d5420f60323a9be1c6b4003af4948675861328d5c0ae74c7cd71031a9102c30af7e63a7586d72b64136263c865b7f3cdd46d8ce
+  metadata.gz: 84f1cc4e7dd87ed3e33f2095d3c0f57c9ad61972ffaa5ed1d9379dfb6bb0e7bc1b07491c76c6c4f4618c39b977d7240689de5552a8c9f60fe1b474c29dde2637
+  data.tar.gz: 1d355a051c6d6f0903c80558019790ab0e1d84adb8885b28b0c18b57802ed16c338ab7793ca24f535dc01980296fcc33b19eacc3acd204d08586db25d63138d4

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.28.0
+
+### Added
+
+- `Issue.list_page_info(...)` returns a `PlanMyStuff::Issue::PageInfo` value object exposing `.issues`, `.page`,
+  `.per_page`, `.has_next?`, and `.has_prev?`. `Issue.list` now delegates to it; return type unchanged
+  (`Array<Issue>`). Closes #63.
+
 ## 0.27.0
 
 ### Added

data/lib/plan_my_stuff/issue.rb

@@ -9,6 +9,21 @@ module PlanMyStuff
   # - `Issue.create!` / `Issue.find` / `Issue.list` return persisted instances
   # - `issue.save!` / `issue.update!` / `issue.reload` for persistence
   class Issue < PlanMyStuff::ApplicationRecord
+    # Value object returned by +Issue.list_page_info+: the fetched issues plus pagination metadata read from the
+    # +Link+ header of the +list_issues+ response. +:total_pages+ is intentionally absent -- GitHub's issues endpoint
+    # is cursor-paginated and never advertises +rel="last"+.
+    #
+    # @!attribute [r] issues
+    #   @return [Array<PlanMyStuff::Issue>]
+    # @!attribute [r] page
+    #   @return [Integer] echo of the requested page
+    # @!attribute [r] per_page
+    #   @return [Integer] echo of the requested per_page
+    PageInfo = Data.define(:issues, :page, :per_page, :has_next, :has_prev) do
+      alias_method :has_next?, :has_next
+      alias_method :has_prev?, :has_prev
+    end
+
     include PlanMyStuff::IssueExtractions::Approvals
     include PlanMyStuff::IssueExtractions::Links
     include PlanMyStuff::IssueExtractions::Viewers
@@ -332,7 +347,38 @@ module PlanMyStuff
       #
       # @return [Array<PlanMyStuff::Issue>]
       #
-      def list(
+      def list(**)
+        list_page_info(**).issues
+      end
+
+      # Lists GitHub issues like +.list+, but returns a +PageInfo+ value object carrying the issues plus pagination
+      # metadata read from the response's +Link+ header in the same request. Use this over +.list+ when a caller needs
+      # to know whether more pages exist (e.g. to render "Next"/"Prev" controls) without an optimistic +page + 1+
+      # probe.
+      #
+      # Shares the entire parameter surface, filtering, and PR-rejection behavior of +.list+; see it for semantics.
+      #
+      # Note the PR-filter wart: +per_page+ caps GitHub's raw item count (issues + PRs), but PRs are stripped
+      # client-side afterward, so +page_info.issues.length+ may be smaller than +per_page+. +has_next?+ comes straight
+      # from the +Link+ header, so it reflects raw items too -- a page can report +has_next? == true+ while showing
+      # fewer than +per_page+ issues.
+      #
+      # @raise [ArgumentError] when +priority_list: false+ is passed, or when +issue_type:+ is an Array
+      # @raise [PlanMyStuff::IssueFieldsNotEnabledError] when +issue_fields:+ is passed and
+      #   +config.issue_fields_enabled+ is +false+
+      #
+      # @param repo [Symbol, String, nil] defaults to config.default_repo
+      # @param state [Symbol] :open, :closed, or :all
+      # @param labels [Array<String>]
+      # @param issue_type [String, Symbol, nil] a single GitHub issue type name
+      # @param issue_fields [Hash{String,Symbol => Object,Range,nil}, nil] GitHub Issue Field equality / range filters
+      # @param priority_list [Boolean, nil] when +true+, restricts to +Priority List+ +Yes+ issues
+      # @param page [Integer]
+      # @param per_page [Integer]
+      #
+      # @return [PlanMyStuff::Issue::PageInfo]
+      #
+      def list_page_info(
         repo: nil,
         state: :open,
         labels: [],
@@ -366,8 +412,16 @@ module PlanMyStuff
         params[:issue_field_values] = field_pairs.join(',') if field_pairs.present?
 
         github_issues = client.rest(:list_issues, resolved_repo, **params)
+        rels = client.last_response&.rels || {}
         filtered = github_issues.reject { |gi| gi.respond_to?(:pull_request) && gi.pull_request }
-        filtered.map { |gi| build(gi, repo: resolved_repo) }
+
+        PageInfo.new(
+          issues: filtered.map { |gi| build(gi, repo: resolved_repo) },
+          page: page,
+          per_page: per_page,
+          has_next: rels[:next].present?,
+          has_prev: rels[:prev].present?,
+        )
       end
 
       # Convenience shortcut for +list(priority_list: true, ...)+. See +.list+ for parameter semantics.

data/lib/plan_my_stuff/version.rb

@@ -3,7 +3,7 @@
 module PlanMyStuff
   module VERSION
     MAJOR = 0
-    MINOR = 27
+    MINOR = 28
     TINY = 0
 
     # Set PRE to nil unless it's a pre-release (beta, rc, etc.)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plan_my_stuff
 version: !ruby/object:Gem::Version
-  version: 0.27.0
+  version: 0.28.0
 platform: ruby
 authors:
 - Brands Insurance